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INTRODUCTION 

In  1976  development  of  the  NS  WC  library  of  numerical  mathematics  subroutines  began. 
The  objective  was  to  form  a  library  of  general  purpose  subroutines  that  would  provide  a 
basic  computational  ability  in  a  variety  of  mathematical  activities.  The  subroutines  were 
to  be  written  in  Fortran.  Even  though  the  subroutines  were  intended  for  use  on  the  CDC 
6000-7000  series  computers,  emphasis  was  to  be  placed  on  their  transportability.  Currently, 
the  library  is  used  on  a  variety  of  computers,  ranging  from  mainframes  such  as  the  CDC 
Cyber  995  to  personal  computers,  such  as  the  IBM  PC.  The  1990  edition  of  the  NSWC 
library  contains  870+  functions  and  subroutines.  This  manual  describes  the  453  functions 
and  subroutines  in  the  library  that  are  available  for  general  use.  (The  remaining  functions 
and  subroutines  are  supportive,  normally  being  of  little  interest  to  most  users.)  A  brief 
appendix  is  included,  which  provides  information  for  installing  the  library. 

All  functions  and  subroutines  are  examined  before  being  accepted  for  the  NSWC  li¬ 
brary.  Primary  considerations  are  the  reliability  and  transportability  of  the  function  or 
subroutine,  its  efficiency  and  ease  of  use,  and  its  generality.  In  regard  to  reliability,  the 
major  concerns  are  accuracy,  the  stability  and  robustness  of  the  algorithm  being  used,  and 
the  overall  quality  of  the  code.  All  routines  are  tested  before  being  accepted  for  the  library. 
The  functions  and  subroutines  in  the  library  are  always  subject  to  reexamination  and  pos¬ 
sible  modification.  When  better  routines  are  obtained,  the  older  routines  are  normally 
eliminated. 

In  regard  to  transportability,  it  is  clear  that  machine  dependent  constants  and  preci¬ 
sion  dependent  algorithms  cannot  be  avoided.  However,  machine  dependent  code  and  I/O 
statements  are  not  permitted.  For  a  function  or  subroutine  to  be  acceptable,  it  is  required 
that  the  coding  satisfy  the  1966  and  1977  ANSI  Fortran  standards,  the  only  exception  being 
the  declaration  of  assumed  size  arrays,  where  the  standards  conflict.  In  this  case,  state¬ 
ments  such  as  REAL  A(l)  and  REAL  A(*)  are  equally  acceptable  for  declaring  as  arrays 
arguments  A  of  a  function  or  subroutine.  Two  versions  of  the  code  for  the  NSWC  library 
are  maintained,  providing  the  appropriate  assumed  size  array  declarations  for  the  1966  and 
1977  standards. 

The  ease  of  use  criterion  is  of  considerable  importance.  The  main  purpose  of  the 
library  is  to  provide  a  service  to  as  broad  an  audience  as  is  possible.  Hence,  it  is  important 
that  duplicate  abilities  be  kept  to  a  minimum,  and  that  the  functions  and  subroutines  be 
as  simple  to  use  and  as  comprehensive  in  scope  as  is  practical.  Development  of  software 
that  satisfies  the  ease  of  use  criterion  can  be  characterized  as  a  packaging  problem,  the 
objective  being  to  package  mathematical  theory  and  formulae  into  comprehensive,  simple 
to  use  functions  and  subroutines.  To  help  meet  this  criterion,  many  specialized  routines 
are  incorporated  into  the  NSWC  library  at  a  subordinate  level,  being  referenced  by  driver 
functions  or  subroutines. 

The  testing  of  the  functions  and  subroutines  serves  many  purposes,  including  deter¬ 
mination  of  the  accuracy  and  efficiency  of  the  software,  checking  for  defects  in  the  code, 
and  searching  for  regions  of  numerical  instability.  In  most  cases,  the  testing  must  be  highly 


1 


selective,  being  used  to  locate  and  examine  weaknesses  in  the  algorithm  and  code.  After  the 
testing  is  finished,  an  assessment  is  made  of  the  utility  and  overall  performance  of  the  code. 
When  the  precision  of  a  function  or  subroutine  can  be  established,  then  this  information  is 
given  with  the  description  of  the  routine.  All  precision  estimates  are  for  the  CDC  6000- 
7000  series  14-digit  single  and  28-digit  double  precision  arithmetics.  The  estimates  do  not 
include  inherent  error.  Thus,  the  accuracy  of  a  code  may  be  better  than  the  inherent 
error  of  the  mathematical  function  that  it  is  computing. 

The  functions  and  subroutines  in  the  NS  WC  library  originate  from  a  variety  of  sources. 
Hence,  standards  concerning  in-line  documentation  and  the  style  of  code  cannot  be  imposed. 
In  gene  red,  all  supportive  routines  not  intended  for  general  usage  are  not  described  in 
the  manual.  This  makes  it  possible  to  modify  or  replace  the  code  without  bothering  the 
programmer.  This  capability  is  extremely  important.  In  the  last  decade,  a  vast  amount 
of  research  has  resulted  in  the  development  of  new,  more  powerful  algorithms  for  a  variety 
of  problems.  Many  of  the  results  affect  current  codes,  occasionally  making  some  codes 
obsolete. 

Distribution  of  the  NSWC  library.  The  NSWC  functions  and  subroutines  are  available  for 
general  use.  The  library  contains  no  proprietary  code. 
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MACHINE  CONSTANTS 


Assume  that  the  integer  arithmetic  being  used  has  base  b,  and  that  the  integers  are 
represented  in  the  form 

±(ko  +  k1b  +  ---  +  kn_1bn~1) 

where  k0, k1}  . . . , kn are  integers  such  that  0  <  ki  <  b  (*  =  0, 1,  . . . , n  -  1).  The  value 
n  is  the  number  of  base  b  digits  fc;,  and  bn  -  1  and  ~(bn  -  1)  are  the  largest  positive  and 
negative  integers  that  occur. 


It  is  assumed  that  the  single  and  double  precision  arithmetics  being  used  have  the  same 
base,  say  ft,  and  that  the  nonzero  numbers  can  be  represented  in  the  form 


+ 


P 


)Pt 


where  k1}  ...,km  are  integers  such  that  0  <  kf  <  ft  (i  =  1,  ...,171),^  >  1,  and  £  is  an 
integer  such  that  £mj„  <  £  <  £max.  The  value  m  is  the  number  of  base  ft  digits  ki,  and 
ki  >  1  is  the  requirement  that  the  floating  point  numbers  are  normalized.  The  values 
£rajn  and  £max  are  the  largest  negative  and  positive  exponents  that  arise  where  the  floating 
point  numbers  maintain  full  m  digit  accuracy.  Then  xmin  =  ftlmia~1  is  the  smallest  positive 
number  that  is  represented  and  xmax  =  (1  —  ft~m)ftta,*x  the  largest. 

Associated  with  m  is  the  constant  e  =  ft~m+1,  called  the  relative  precision  of  the 
floating  point  arithmetic  being  used.  Theoretically,  e  is  the  smallest  number  for  which  1  +  e, 
when  stored  in  memory,  is  stored  exactly  and  has  a  value  greater  than  1.  Normally  e  will 
be  the  smallest  number  that  satisfies  these  conditions.  However,  there  do  exist  computer 
arithmetics  (such  as  the  CDC  6000-7000  series  double  precision  arithmetics)  for  which  this 
is  not  the  case.  In  such  arithmetics,  some  arithmetic  results  are  able  to  be  stored  more 
accurately  than  others. 


The  functions  SPMPAR,  DPMPAR,  and  IPMPAR  are  available  for  obtaining  the  above 
constants.  IPMPAR  is  the  only  subprogram  in  the  NSWC  library  that  is  machine  depen¬ 
dent. 

SPMPAR(j) 

SPMPAR  is  a  real  valued  function.  It  is  assumed  that  *  =  1, 2,  or  3.  SPMPAR  provides 
the  following  constants  for  the  single  precision  arithmetic  being  used: 

SPMPAR(l)  =  c,  the  relative  precision 
SPMPAR(2)  =  Xminj  the  smallest  positive  number 
SPMPAR(3)  =  xmax)  the  largest  positive  number 


Programming.  SPMPAR  was  written  by  A.  H.  Morris.  The  function  IPMPAR  is  used. 
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DPMPAR(t) 

DPMPAR  is  a  double  precision  valued  function.  It  is  assumed  that  i  =  1,2,  or  3. 
DPMPAR  provides  the  following  constants  for  the  double  precision  arithmetic  being  used: 

DPMPAR(l)  =  e,  the  relative  precision 
DPMPAR(2)  =  im;n,  the  smallest  positive  number 
DPMPAR(3)  =  xmax, the  largest  positive  number 

DPMPAR  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Programming.  DPMPAR  was  written  by  A.  H.  Morris.  The  function  IPMPAR  is  used. 

IPMPAR(i) 

IPMPAR  is  an  integer  valued  function.  It  is  assumed  that  «  =  1,  ... .  ,10.  IPMPAR 
provides  the  following  constants: 

Integer  arithmetic 

IPMPAR(l)  =  b,  the  base  of  the  arithmetic 
IPMPAR(2)  =  n,  the  number  of  base  b  digits 
IPMPAR  (3)  =  bn  —  1,  the  largest  integer 

Base  for  the  floating  arithmetics 
IPMPAR  (4)  =  0 

Single  precision  arithmetic 

IPMPAR(5)  =  m,  the  number  of  base  /?  digits 
IPMPAR(6)  =  £min,  the  largest  negative  exponent 
IPMPAR(7)  =  £max,  the  largest  positive  exponent 

Double  precision  arithmetic 

IPMPAR(8)  =  m,  the  number  of  base  (3  digits 
IPMPAR(9)  =  £min,  the  largest  negative  exponent 
IPMPAR(IO)  =  £max,  the  largest  positive  exponent 

Programming.  IPMPAR  is  an  adaptation  by  A.  H.  Morris  of  the  function  I1MACH,  de¬ 
signed  by  P.  A.  Fox,  A.  D.  Hall,  and  N.  L.  Schryer  (Bell  Laboratories).  The  constants  for 
the  various  computers  are  from  Bell  Laboratories,  NSWC,  and  other  sources. 
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SORTING  LISTS 


Let  A  be  an  array  containing  n  >  1  elements  a\,  . . . ,  an.  Then  the  following  subroutines 
are  available  for  reordering  the  elements  of  A. 

CALL  ISHELL(A,n) 

It  is  assumed  that  A  is  an  integer  array.  When  ISHELL  is  called,  the  elements  of  A 
are  reordered  so  that  a;  <  a,-+1  for  *  =  1,  . . . ,  n  —  1. 

Algorithm.  The  Shell  sorting  algorithm  with  increments  (3*  —  l)/2  is  employed. 
Programmer.  A.  H.  Morris 

Reference.  Knuth,  D.  E.,  The  Art  of  Computer  Programming.Vol.  3,  Sorting  and  Search¬ 
ing.  Addison- Wesley,  Reading,  Mass.,  1973,  pp.  84-95. 

CALL  SHELL(A,n) 

CALL  AORD(A,n) 

It  is  assumed  that  A  is  a  real  array.  If  SHELL  is  called,  then  the  elements  of  A  are 
reordered  so  that  for  i  =  1,  ...  ,n  -  1.  Otherwise,  if  AORD  is  called,  then  the 

elements  of  A  are  reordered  so  that  |a,|  <  |at+i|  for  *  =  1,  . . . ,  n  —  1. 

Programmer.  A.  H.  Morris 

CALL  RISORTfA, L,n) 

It  is  assumed  that  A  is  a  real  array  and  L  an  integer  array  containing  n  elements.  When 
RISORT  is  called,  the  elements  of  A  are  reordered  so  that  <  <^+1  for  t  =  1,  . . .  ,n  —  1. 
The  same  permutations  are  performed  on  L  as  on  A,  thereby  reordering  the  elements  of  L 
so  as  to  correspond  with  the  new  ordering  of  A. 

Remark.  RISORT  is  normally  used  for  obtaining  the  indices  of  the  reordered  elements  of 
A.  If  L  initially  contains  the  values  1,  . . . ,  n  and  atl ,  . . . ,  at„  is  the  reordered  sequence  of 
elements  of  A,  then  L  contains  the  indices  tj,  . . .  ,tn  when  RISORT  terminates. 

Programmer.  A.  H.  Morris 

CALL  SHELL2(A,  B,  n) 

It  is  assumed  that  A  and  B  are  real  arrays  containing  n  elements.  When  SHELL2  is 
called,  the  elements  of  A  are  reordered  so  that  a,  <  a,+1  for  i  =  1,  . . . ,  n  —  1.  The  same 
permutations  are  performed  on  B  as  on  A,  thereby  reordering  the  elements  of  B  so  as  to 
correspond  with  the  new  ordering  of  A. 

Programmer.  A.  H.  Morris 
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CALL  DSORT(A,n) 

CALL  DAORD(A,n) 

It  is  assumed  that  A  is  a  double  precision  array.  If  DSORT  is  called,  then  the  elements 
of  A  are  reordered  so  that  a*  <  a,-+i  for  t  =  1,  . . . ,  n  —  1.  Otherwise,  if  DAORD  is  called, 
then  the  elements  of  A  are  reordered  so  that  |a,|  <  |  a»_)_  1 1  for  t  =  1,  . . . ,  n  —  1. 

Programmer.  A.  H.  Morris 

CALL  DISORT(A,  L,  n) 

It  is  assumed  that  A  is  a  double  precision  array  and  L  an  integer  array  containing  n 
elements.  When  DISORT  is  called,  the  elements  of  A  are  reordered  so  that  a*  <  for 
»  =  1,  . . .  ,n  —  1.  The  same  permutations  are  performed  on  I  as  on  A,  thereby  reordering 
the  elements  of  L  so  as  to  correspond  with  the  new  ordering  of  A. 

Programmer.  A.  H.  Morris 

CALL  DDSORT(A,R,n) 

It  is  assumed  that  A  and  B  are  double  precision  arrays  containing  n  elements.  When 
DDSORT  is  called,  the  elements  of  A  are  reordered  so  that  a*  <  a,-+i  for  i  =  1,  . . . ,  n  —  1. 
The  same  permutations  are  performed  on  B  as  on  A,  thereby  reordering  the  elements  of  B 
so  as  to  correspond  with  the  new  ordering  of  A. 

Programmer.  A.  H.  Morris 
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CUBE  ROOT 


The  following  functions  are  available  for  computing  the  real  cube  root  of  a  real  number. 

CBRT  (a:) 

DCBRT(x) 

CBRT  is  used  if  x  is  a  single  precision  number,  and  DCBRT  is  used  if  x  is  a  double 
precision  number.  CBRT  is  a  single  precision  function  and  DCBRT  a  double  precision 
function.  The  value  of  the  function  is  <tfx. 

Remark.  DCBRT  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  A.  H.  Morris 

FOUR  QUADRANT  ARCTANGENT 

The  function  ARTNQ  is  similar  to  the  ATAN2  function,  the  differences  being  that  its 
value  lies  in  the  interval  [0,2jt)  and  its  value  at  the  origin  is  0.  DARTNQ  is  the  double 
precision  counterpart  of  ARTNQ. 

ARTNQ(y,x) 

DARTNQ(y,  x) 

ARTNQ  is  used  if  x  and  y  are  single  precision  values,  and  DARTNQ  is  used  if  x  and 
y  are  double  precision  values.  ARTNQ  is  a  single  precision  function  and  DARTNQ  is  a 
double  precision  function. 

If  (x,  y)  is  a  point  in  the  plane  other  than  the  origin  (0,0),  let  L  denote  the  straight 
line  connecting  the  points  (0,0)  and  (x,y).  Then  the  function  is  assigned  the  value  0  where 
9  is  the  angle  between  L  and  the  positive  x-axis  measured  in  a  counterclockwise  direction. 
Here  0  <  6  <  2i r.  Otherwise,  if  ( x,y )  is  the  origin  (0,0),  then  the  function  is  assigned  the 
value  0. 

Remark.  DARTNQ  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  Richard  Pasto 


LENGTH  OF  A  TWO-DIMENSIONAL  VECTOR 

The  following  functions  are  available  for  computing  the  length  of  a  real  vector  (x,y). 

CPABS(x,  y) 

DCPABS(x,y) 
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GPABS  is  used  if  x  and  y  are  single  precision  values,  and  DCPABS  is  used  if  x  and  y 
are  double  precision  values.  CPABS  is  a  single  precision  function  and  DCPABS  is  a  double 
precision  function.  The  value  of  the  function  is  y/x2  +  y2. 

Remark.  DCPABS  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  A.  H.  Morris 
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RECIPROCAL  OF  A  COMPLEX  NUMBER 


The  following  subroutines  are  available  for  computing  the  reciprocal  of  a  complex 
number. 

CALL  CREC(x,  y,  u,v) 

CALL  DCREC(x,y,  u,  v) 

CREC  is  used  if  x  and  y  are  single  precision  real  numbers  and  u  and  v  real  variables, 
and  DCREC  is  used  if  x  and  y  are  double  precision  numbers  and  u  and  v  double  precision 
variables.  It  is  assumed  that  x  and  y  are  the  real  and  and  imaginary  parts  of  a  nonzero 
complex  number  z.  When  CREC  or  DCREC  is  called,  u  and  v  are  set  to  the  real  and 
imaginary  parts  of  1  /z,  respectively. 

Programmer.  A.  H.  Morris 


SQUARE  ROOT  OF  A  DOUBLE  PRECISION  COMPLEX  NUMBER 

The  following  subroutine  is  available  for  computing  the  square  root  of  a  double  precision 
complex  number. 

CALL  DCSQRT(^,  W) 

Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is  assumed  that  Z(  1)  and  Z{2) 
are  the  real  and  imaginary  parts  of  a  complex  number  z.  When  DCSQRT  is  called,  if  z  =  0 
then  W (1)  and  W (2)  are  set  to  0.  Otherwise,  if  z  5^  0  then  the  square  root  w  =  y/z  where 
-tt/2  <  arg(tn)  <  jt/2  is  computed  and  stored  in  W.  W(l)  and  W( 2)  contain  the  real  and 
imaginary  parts  of  w,  respectively. 

Note.  Z  and  W  may  reference  the  same  storage  area. 

Programming.  DCSQRT  calls  the  function  DCPABS.  DCSQRT  was  written  by  A.  H. 
Morris. 
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CONVERSION  OF  POLAR  TO  CARTESIAN  COORDINATES 


The  following  subroutine  is  available  for  converting  polar  coordinates  (r,  0)  to  cartesian 
coordinates  (x,  y). 

CALL  POCA(r,  0,x,  y) 

Let  (r,  6)  be  the  polar  coordinates  of  a  point  in  the  plane  and  let  x,  y  be  variables. 
When  the  routine  is  called,  x  and  y  are  assigned  the  values  x  =  r  cos  6  and  y  =  rsin  9. 


CONVERSION  OF  CARTESIAN  TO  POLAR  COORDINATES 

The  following  subroutine  is  available  for  converting  cartesian  coordinates  (x,  y)  to  polar 
coordinates  (r,  6). 

CALL  CAPO(x,y,r,  9) 

Let  ( x ,  y)  be  the  cartesian  coordinates  of  a  point  in  the  plane  and  let  r,  9  be  variables. 
If  ( x ,  y)  is  the  origin  then  CAPO  sets  r  =  6  =  0.  Otherwise,  if  (x,  y)  is  a  point  other  than 
the  origin,  let  L  denote  the  straight  line  connecting  the  points  (0,0)  and  (x,y).  Then  when 
CAPO  is  called,  r  is  assigned  the  value  \Jx2  +  y2  and  9  is  defined  to  be  the  angle  between 
L  and  the  positive  x  axis.  Here  —  jr  <  8  <  it. 


ROTATION  OF  AXES 

Let  (zi,yi)  be  the  (cartesian)  coordinates  for  a  point  in  the  plane.  The  following 
subroutine  computes  the  new  coordinates  (x2,y2)  for  the  point  after  the  x,y  axes  have 
been  rotated  by  an  angle  6. 

CALL  ROTA(xi,y1,0,x3,y2) 

The  arguments  x2  and  y2  are  variables.  When  ROTA  is  called,  x2  and  y2  are  assigned 
the  values: 

x2  =  xi  cos  8  +  yi  sin  8 
y2  =  —  xi  sin  8  +  yi  cos  8 

Programmer.  A.  H.  Morris. 
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PLANAR  GIVENS  ROTATIONS 


If  a  and  b  are  real  numbers  where  a2  +  b2  ^  0,  then  there  is  an  orthogonal  matrix 
( _^  such  that  (_^  ^)(^)  =  (^).  In  this  case  r2  =  a2  +  b2,c  =  a/r,  and  s  =  b/r. 

The  matrix  (  S )  represents  what  is  called  a  Givens  rotation.  Given  a  and  6,  the 
'  —  s  c'  ’ 

matrix  is  uniquely  defined  up  to  the  sign  of  r.  For  any  real  a,  let  sgn(a)  =  1  if  a  >  0  and 

sgn(a)  =  -1  if  a  <  0.  If  we  define  r  =  oVa2  +  b 2  where 


sgn(a) 

sgn(6) 


if  |a[  >  \b\ 
if  |a|  <  |6| 


then  for  r  ^  0  we  note  that  |c|  >  |s|  implies  c  >  0,  and  that  |c|  <  |s|  implies  s  >  0.  For 
convenience,  when  r  =  0  we  set  c  =  1  and  s  =  0. 


The  value  <r  is  not  needed  for  the  constuction  of  a  Givens  rotation  matrix,  but  its  use 
permits  the  representation  of  c  and  s  by  a  single  value  z.  For  each  c  and  s,  z  is  defined  as 
follows: 


(  s  if  |s|  <  c  or  c  =  0 

1  1/c  if  0  <  jc|  <  s 


The  mapping  (c,s)  i-+  z  is  1-1.  If  the  user  wishes  to  reconstruct  c  and  s  from  z,  then  this 
can  be  done  as  follows: 


If  z  =  1  then  set  c  =  0  and  s  =  1. 

If  \z\  <  1  then  set  c  =  \j\  —  z2  and  s  =  z. 

If  \z\  >  1  then  set  c  =  \  jz  and  s  =  Vl  —  c2. 

The  subroutines  SROTG  and  DROTG  are  available  for  computing  c,s,r,  and  z.  SROTG 
is  used  when  a  and  b  are  single  precision  real  numbers,  and  DROTG  is  used  when  a  and  b 
are  double  precision  numbers. 

CALL  SROTG(AR,BZ,C,  5) 

CALL  DROTG(AR,BZ,C',  S) 

When  SROTG  is  used  then  AR,  BZ,  C,  and  S  are  real  variables.  Otherwise,  when 
DROTG  is  used  then  AR,  BZ,  C,  and  S  are  double  precision  variables.  On  input,  AR  =  a 
and  BZ  =  6.  When  the  routine  terminates  AR  =  r,  BZ  =  z,  C  =  c,  and  S  —  s. 


Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  SROTG 
and  DROTG  were  coded  by  Charles  Lawson  (Jet  Propulsion  Laboratory). 
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THREE  DIMENSIONAL  ROTATIONS 


If  A  =  (dij)  is  a  3  x  3  orthogonal  matrix,  then  A  can  be  represented  in  the  form 
A  =  R3R2R1E  where 


/I 

0 

°  \ 

f  COS  62 

0 

—sin  02  \ 

Ri  =  0 

cos  9\ 

—sin  Ox  J 

Ri  —  |  0 

1 

°  ) 

Vo 

sin  Ox 

cos  9 1  J 

V  sin  62 

0 

cos  9 2  J 

/cos  9 3 

—sin  Oz 

°\ 

n 

0 

0  \ 

R3  =  (  sin  Oz 

cos  Oz 

0 

E=  (  0 

1 

° 

V  0 

0 

l) 

Vo 

0 

±1/ 

Rx  represents  a  rotation  around  the  z-axis,  R2  a  rotation  around  the  y-axis,  and  R3  a 
rotation  around  the  z-axis.  Since  A  is  orthogonal  the  determinant  det(A)  =  ±1.  If  det(A) 
=  1  then  E  is  the  identity  matrix  and  A  is  the  combined  rotation  R3R2R1  .  If  det(A)  =  — 1 
then  A  is  composed  of  the  rotation  R3R2R1  and  the  reflection  E  =  diag(l,  1,  —  1).  The 
following  subroutine  is  available  for  finding  the  angles  where  —  sr  <9 1  <  Jr,  |0j|  < 

jt/2,  and  —  x  <  $3  <  x. 

CALL  ROT3(A,  THETA) 

THETA  is  an  array  of  dimension  3  or  larger.  When  ROT3  is  called,  the  angles  61,62, 03 
are  computed  and  stored  in  THETA. 


Algorithm.  If  an  =  021  =  0  then  let  #3  =  0.  Otherwise,  let  #3  =  ATAN2(a2i,an).  Then 


R\A  = 


ri 

d'xz 

a13 

0 

a22 

a23 

^31 

a.32 

033 

)-A' 


where  r\  =  > Ja\x  +  a\x.  Also,  if  62  =  ATAN2(a3i,ri)  then 


=  A" 


where  r2  =  \/r\  +  a|2.  Since  f2  >  0,  by  orthogonality  it  follows  that  r2  =  1  and  a'/2  = 


ai3  —  0.  Finally,  if  9 1  =  ATAN2(a32,a22)  then 


/ 1  0  0  \ 

R\A"  -  I  0  r3  a'2'3 
VO  0  a'^J 

where  r3  =  \/(a22)2  +  (a2i)2-  Since  r3  >  0,  by  orthogonality  we  obtain  r3  =  1,  a23  =  0, 
and  033  =  ±1. 


Programmer.  A.  H.  Morris 
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ROTATION  OF  A  POINT  ON  THE  UNIT  SPHERE  TO  THE  NORTH  POLE 


Given  the  point  (x,  y,  z )  where  x2  +  y2  +  z1  =  1.  Then  there  exist  orthogonal  matrices 

/I  0  0  \  (Cy  0  -a„\ 

^=10  cx  -sx  1  and  Ry  =  I  0  1  0 

V  0  Sx  Cx  J  V  Sy  0  Cy  J 


such  that  0  J  .  Rx  represents  a  rotation  about  the  x-axis  and  Ry  a  rotation 

about  the  y-axis.  The  following  subroutine  is  available  for  obtaining  the  values  cx,sx,cy,sy. 
CALL  CONSTR(x,y)z,CX,SX,CY,SY) 


CX,SX,CY,SY  are  variables.  When  CONSTR  is  called,  these  variables  are  assigned 
the  values  cx,sx,cy,sy. 

Programmer.  Robert  J.  Renka  (Oak  Ridge  National  Laboratory) 
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HYPERBOLIC  SINE  AND  COSINE  FUNCTIONS 


The  following  subroutine  is  available  for  computing  sinh(x)  —  x,  cosh(x)  —  1,  and 
cosh(x)  —  1  —  x1  j 2  for  real  x. 

CALL  SNHCSH(S,C,x,  IND) 

S  and  C  are  variables,  and  IND  is  an  input  argument  which  specifies  the  functions  to 
be  computed.  IND  takes  the  values: 

IND  =  —  1  if  only  sinh(x)  —  x  is  desired. 

IND  =  0  if  sinh(x)  —  x  and  cosh(x)  —  1  are  desired. 

IND  =  1  if  only  cosh(x)  —  1  is  desired. 

IND  =  2  if  only  cosh(x)  —  1  —  x2/2  is  desired. 

IND  =  3  if  sinh(x)  —  x  and  cosh(x)  —  1  —  x2/2  are  desired. 

S  is  assigned  the  value  sinh(x)  -  x  if  this  function  is  requested.  When  cosh(x)  —  1  or 
cosh(x)  —  1  —  x2/2  is  computed  then  the  value  is  stored  in  C. 

Precision.  For  all  x,  sinh(x)  —  x  has  a  relative  error  less  than  2.3E-14,  cosh(x)  —  1  has  a 
relative  error  less  than  2.2E-14,  and  cosh(x)  —  1  —  x2/2  has  a  relative  error  less  than  3.8E-14. 

Programming.  Written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 
Modified  by  A.  H.  Morris. 
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EXPONENTIALS 


The  functions  REXP  and  DREXP  are  available  for  computing  ex  —  1.  DREXP  is  a 
double  precision  function. 

REXP  (a:) 

REXP(x)  =  ex  —  1  for  real  x. 

Algorithm.  See  pages  378-379  and  appendix  B  of  the  reference. 

Precision.  REXP(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit  when  REXP(x) 

#0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programmer.  A.  H.  Morris 

DREXP(x) 

The  argument  x  is  a  double  precision  number.  DREXP  (x)  is  the  double  precision  value 
for  ex  -  1. 

Remark.  DREXP  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DREXP(x)  is  accurate  to  within  1  unit  of  the  28th  significant  digit  when 
DREXP  (x)  ^  0. 

Programming.  DREXP  was  written  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 


21 


LOGARITHMS 


The  functions  ALNREL,  RLOG,  RLOG1,  DLNREL,  DRLOG,  and  DRLOG1  are  avail¬ 
able  for  computing  ln(l  +  a),  x  -  1  -  ln(x),  and  a  -  ln(l  +  a).  DLNREL,  DRLOG,  and 
DRLOG1  are  double  precision  functions. 

ALNREL(a) 

ALNREL(a)  =  ln(l  +  a)  for  a  >  —  1. 

Algorithm.  See  page  378  and  appendix  A  of  the  reference. 

Precision.  ALNREL(a)  is  accurate  to  within  2  units  of  the  14th  significant  digit  when 
ALNREL(a)  +  0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programmer.  A.  H.  Morris 
RLOG(x) 

RLOG(x)  =  x  —  l  —  ln(x)  for  x  >  0. 

Algorithm.  See  page  379  and  appendix  E  of  the  reference. 

Precision.  RLOG(x)  is  accurate  to  within  3  units  of  the  14th  significant  digit  when 
RLOG(x)  #0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programmer.  A.  H.  Morris 
RLOGl(a) 

RLOGl(a)  =  a  -  ln(l  +  a)  for  a  >  —1. 

Algorithm.  See  page  379  and  appendix  E  of  the  reference. 

Precision.  RLOGl(a)  is  accurate  to  within  3  units  of  the  14th  significant  digit  when 
RLOG  1(a)  #0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programmer.  A.  H.  Morris 
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DLNREL(a) 

The  argument  a  is  a  double  precision  number  where  a  >  —  1.  DLNREL(a)  is  the  double 
precision  value  for  ln(l  +  a). 

Remark.  DLNREL  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DLNREL(a)  is  accurate  to  within  1  unit  of  the  28th  significant  digit  when 
DLNREL(a)  ^  0. 

Programming.  DLNREL  was  written  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 

DRLOG(z) 

The  argument  a;  is  a  positive  double  precision  number.  DRLOG(x)  is  the  double  pre¬ 
cision  value  for  x  —  1  —  ln(x). 

Remark.  DRLOG  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DRLOG(x)  is  accurate  to  within  2  units  of  the  28th  significant  digit  when 
DRLOG(x)  ^0. 

Programming.  DRLOG  was  written  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 
DRLOGl(a) 

The  argument  a  is  a  double  precision  number  a  >  —1.  DRLOGl(a)  is  the  double 
precision  value  for  a  —  ln(l  +  a). 

Remark.  DRLOG  1  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DRLOGl(o)  is  accurate  to  within  2  units  of  the  28th  significant  digit  when 
DRLOGl(a)  ^  0. 

Programming.  DRLOG1  was  written  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 
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DETERMINING  IF  A  POINT  IS  INSIDE  OR  OUTSIDE  A  POLYGON 

Given  a  sequence  of  points  =  (x»,y,)  (*  =  1, . .  .,n).  Let  r  denote  the  polygonal  line 
which  begins  at  point  iq,  traverses  the  points  i \  in  the  order  that  they  are  indexed,  and 
is  the  straight  line  segment  connecting  iq  to  vi+1  for  each  i  =  1,  . . . ,  n  -  1.  It  is  assumed 
that  vn  —  V\,  or  that  there  is  also  a  straight  line  segment  from  vn  to  iq  when  vn  ^  V\. 
Consequently,  the  polygonal  path  r  is  a  loop  beginning  and  ending  at  v\. 

For  any  point  vq  —  (^o,  yo)  not  on  the  path  r,  let  r/(r,  i/q)  denote  the  winding  number 
of  the  path  r  around  the  point  Vq  .  Then  t)(t,  uq)  =  0  if  i/0  is  outside  the  polygon  whose 
boundary  is  r.  If  u0  is  inside  the  path  then  r?(r,  v0)  =  m  where  mis  an  integer.  If  m  >  0  then 
the  path  r  loops  m  times  in  a  counterclockwise  direction  around  the  point  vq  .  Otherwise, 
if  m  <  0  then  r  loops  |m|  times  in  a  clockwise  direction  around  i/0. 

Given  an  arbitrary  point  v0  =  (x0,y0)}  the  following  subroutine  is  available  for  deter¬ 
mining  whether  v0  is  on  the  path,  outside  the  path,  or  inside  the  path.  If  the  point  uQ  is 
inside  r  then  the  winding  number  r?(r,  v0)  =  m  is  also  computed. 

CALL  LOCPT(z0,yo,*,Y,n,£,m) 

It  is  assumed  that  n  >  1.  X  and  Y  are  arrays  containing  x\  ...  ,xn  and  jq,  . . . ,  y„. 
The  arguments  i  and  m  are  variables.  When  LOCPT  terminates  t  has  one  of  the  following 
values: 

&=  -1  if  (a:o>!/o)  is  outside  the  path 
£=  0  if  (z0,  yo)  lies  on  the  path 

£—  1  if  (xq,  yo)  is  inside  the  path 

The  variable  m  is  assigned  the  value  0  if  (z0,y0)  is  on  or  outside  the  path.  If  (x0,y0)  is 
inside  the  path  then  m  =  the  winding  number  of  the  path  r  around  the  point  (s0,yo)- 

Remark.  There  are  no  restrictions  on  the  points  (x»,y,).  Consequently,  the  path  may 
intersect  itself. 

Programming.  The  function  SPMPAR  is  used.  LOCPT  was  written  by  A.  H.  Morris. 
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THE  CONVEX  HULL  FOR  A  FINITE  PLANAR  SET 


If  (zi,yi),  • .  ■ ,  {xm,ym)  are  m  distinct  points  in  the  plane,  then  the  following  subrou¬ 
tine  is  available  for  finding  the  smallest  convex  polygon  which  with  its  interior  contains  the 
points. 

CALL  HU  LLpf,  Y,  m,  BX,BY,  k,  VX,VY,  n) 

It  is  assumed  that  m  >  2.  X  and  Y  are  arrays  containing  the  abscissas  xi,  . . . ,  xm  and 
ordinates  yls  . ..,yTO,  respectively.  When  HULL  is  called  the  points  are  reordered  so  that 
yi  <  *  •  •  <  ym-  Thus  X  and  Y  may  be  modified  when  the  routine  terminates. 

BX  and  BY  are  arrays  of  dimension  m  +  1  or  larger,  and  It  is  a  variable.  When  HULL 
terminates,  BX  and  BY  contain  the  abscissas  and  ordinates  of  the  points  (xi,yi)  which  he 
on  the  boundary  of  the  desired  convex  polygon,  and  k  =  the  number  of  points  stored  in 
BX  and  BY.  If  BX  and  BY  contain  the  abscissas  x[,  ...,x'k  and  ordinates  y[,  ...  ,y'k,  then 
the  points  (x(-,yj)  are  indexed  in  the  order  they  occur  when  traversing  the  boundary  in  a 
counterclockwise  manner.  Also  (x^,y^)  =  (xj,yi). 

VX  and  VY  are  arrays  of  dimension  m  +  1  or  larger,  and  n  is  a  variable.  When 
HULL  terminates,  VX  and  VY  contain  the  abscissas  and  ordinates  of  the  vertices  of  the 
desired  convex  polygon,  and  n  =  the  number  of  points  stored  in  VX  and  VY.  If  VX  and 
VY  contain  the  abscissas  x",  ... . ,  x"  and  ordinates  y'{,  . . . ,  y",  then  the  vertices  (x^',  y")  are 
indexed  in  the  order  they  occur  when  traversing  the  boundary  of  the  convex  polygon  in  a 
counterclockwise  manner.  Also  (x^,y^)  =  {x'{,  y"). 

Example.  Assume  that  we  are  given  the  points 
(-1,-3),  (1,1),  (0,3),  (2,2),  (-2,4),  (-1,-1). 

When  HULL  is  called  X  and  Y  are  reordered 
and  we  obtain: 

X  contains  — 1,-1, 1,2,0, -2 
Y  contains  —3, —1,1,2, 3,4 
BX  contains  —1,2,0, -2,-1 
BY  contains  —3, 2, 3, 4, —3 
VX  contains  —1,2,— 2,-1 
VY  contains  —3,2,4, —3 


Programming.  HULL  calls  the  subroutine  RRSORT  and  function  SPMPAR.  HULL  was 
written  by  A.  H.  Morris. 
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AREAS  OF  PLANAR  POLYGONS 


Given  a  sequence  of  points  t/,-  =  (z,-,y,)  (*  =  1,  . . .  ,n  +  1)  where  n  >  1  and  v„+1  =  vi . 
Let  t  denote  the  polygon  whose  boundary  dr  is  a  polygonal  line  which  begins  at  point  vj , 
traverses  the  points  in  the  order  that  they  are  indexed,  and  is  the  straight  line  segment 
connecting  v,  to  for  t  =  1,  . . .  ,n.  Then  the  function  PAREA is  available  for  computing 
A(t)  =  ffr  dxdy.  If  the  boundary  dr  is  a  positively  (negatively)  oriented  simple  closed 
curve,  then  A(r)  is  positive  (negative)  and  |A(r)|  =  the  area  of  r.  However,  dr  need  not  be 
simple.  It  may  be  self-intersecting  or  have  overlapping  line  segments. 

PAREA(X,Y,iV) 

X  and  Y  are  arrays  containing  the  abscissas  xi,  ... ,x #  and  ordinates  yj,  ...,yN, 
respectively.  The  argument  N  may  have  the  value  norn  +  l.  Since  t;„+i  =  iq, xn+i  and 
y„+i  are  not  required  to  appear  in  X  and  Y.  PAREA  (A,  Y,  N)  is  assigned  the  value  A(r). 

Programmer.  A.  H.  Morris 

Reference.  DiDonato,  A.  R.  and  Hageman,  R.  K.,  Computation  of  the  Integral  of  the  Bi¬ 
variate  Normal  Distribution  over  Arbitrary  Polygons,  Report  TR  80-166,  Naval  Surface 
Weapons  Center,  Dahlgren,  Virginia,  1980. 
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HAMILTONIAN  CIRCUITS 

Given  a  directed  graph  G  containing  n  vertices,  denoted  by  the  integers  1,  . . . ,  n.  Then 
any  circuit  of  n  arcs  which  traverses  the  n  vertices,  say  in  the  order  »i,  . . .  ,*n,  is  called  a 
Hamiltonian  circuit.  For  convenience,  it  is  assumed  that  for  any  two  vertices  *  and  j,  no 
more  than  one  arc  exists  which  begins  at  »  and  ends  at  j.  Then  the  following  subroutine  is 
available  for  finding  the  Hamiltonian  circuits  of  G,  if  any  exist. 

CALL  HC(IND,  m,  n,  P,  A,  NB,  S,  IWK.NUM) 

The  argument  m  is  the  number  of  arcs  in  the  graph  G.  P  is  an  integer  array  of 
dimension  n  +  1  and  A  an  integer  array  of  dimension  m.  The  graph  is  stored  in  P  and  A 
as  follows:  For  «  =  1,  . . . ,  n  let 

R%  =  {j:  there  exists  an  arc  which  begins  at  i  and  ends  at  j}. 

Then  the  vertices  in  Pi,  . . . ,  Rn  are  stored  in  A,  where  the  data  in  Ri  precedes  the  data  in 
R%+i  for  *  =  1,  . . . ,  n  —  1.  For  each  the  vertices  in  Ri  may  be  given  in  any  order  in  A. 
The  array  P  contains  the  data 

P(1)=0 

P(*  +  1)  =  the  total  number  of  vertices  in  Ri,  . ..  ,Rf  (*  =  1,  . .  .,n). 

Hence,  if  P(»)  <  P(:  + 1)  then  the  vertices  in  Ri  are  found  in  locations  P(i')  +  1,  . . .  ,P(t  +  l) 
of  A.  Otherwise,  if  P(t)  =  P(t  +  1)  then  Ri  =  <f>  (the  empty  set);  i.e.,  there  are  no  arcs  in 
G  which  begin  at  t  (and  no  Hamiltonian  circuits  exist).  Also,  P(n+ 1)  =  m  since  there  are 
m  arcs  in  G. 

Example.  Consider  the  graph  where 
m  =  5,n  =  4 
Ri  —  {2,4}  Rz  =  <f> 

P2  =  {1,3}  P4  =  { 3}. 

Then  A  contains  4, 2, 1,3, 3 
P  contains  0,2, 4, 4, 5. 

When  HC  is  called,  a  depth-first  tree  search  employing  backtracking  is  used.  NB  is  a 
variable  for  controlling  the  backtracking.  If  NB  >  0  on  input,  then  it  is  assumed  that  NB  is 
the  maximum  number  of  backtracks  that  may  be  performed  to  find  a  Hamiltonian  circuit. 
Otherwise,  if  NB  <  0  then  it  is  assumed  that  no  restriction  is  placed  on  the  backtracking. 
When  HC  terminates,  NB  =  the  number  of  backtracks  that  were  actually  performed. 

S  is  an  integer  array  of  dimension  n.  When  HC  is  called,  if  a  Hamiltonian  circuit  is 
found  which  traverses  the  vertices,  say  in  the  order  «i,  then  the  ordered  vertices 

»i,  . . .  ,*'n  are  stored  in  S. 

IWK  is  an  array  of  dimension  NUM  that  is  a  work  space  for  the  routine.  It  is  assumed 
that  NUM  >  m  +  8n  +  20. 
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Only  one  Hamiltonian  circuit  will  be  obtained  on  a  call  to  HC.  However,  this  routine 
can  be  repeatedly  called  to  obtain  all  the  Hamiltonian  circuits.  IND  is  a  variable  which 
controls  the  operation  of  the  routine  on  input,  and  reports  the  status  of  the  results  on 
output.  It  is  assumed  that  IND  =  0  on  the  first  call  to  HC.  When  the  routine  terminates, 
if  no  input  errors  are  detected  then  IND  has  one  of  the  following  values: 

IND  =  1  A  Hamiltonian  circuit  was  found  and  the  ordered  vertices  traversed 
by  the  circuit  stored  in  S.  To  find  another  circuit,  reset  NB  and 
recall  the  routine. 

IND  =  2  The  maximum  number  of  backtracks  were  performed.  To  continue, 
reset  NB  and  recall  the  routine. 

IND  =  4  No  more  circuits  exist.  The  array  A  has  been  restored  (see  the 
remark  on  the  storage  of  A  below)  and  the  procedure  is  finished. 

We  note  in  passing  that  on  an  initial  call  to  the  routine,  the  setting  IND  =  4  on  output 
indicates  that  the  graph  contains  no  Hamiltonian  circuits. 

After  a  call  to  HC,  if  IND  =  1  or  2  on  output  then  the  search  procedure  can  be 
continued  by  resetting  NB  and  recalling  the  routine.  Do  not  modify  IND  when  the  tree 
search  is  to  be  continued.  In  this  case,  the  storage  of  A  has  been  temporarily  modified 
and  IWK  contains  information  needed  for  the  search.  If  a  new  Hamiltonian  circuit  is  found 
when  HC  is  recalled,  then  the  vertices  traversed  by  the  new  circuit  will  now  be  stored  in  S. 

After  a  call  to  HC,  if  IND  =  1  or  2  on  output  and  it  is  desired  that  the  search  procedure 
be  terminated,  then  reset  IND  =  3  and  recall  the  routine.  In  this  case,  the  array  A  will  be 
restored  and  IND  =  4  when  HC  terminates. 

Storage  of  A.  When  A  is  restored,  the  order  of  the  vertices  of  Ri  in  A  may  be  modified 
for  each  t. 

Error  Return.  If  an  input  error  is  detected  then  IND  is  set  to  one  of  the  following  values: 
IND  =  —  1  IND  <  0  or  IND  >  3  on  input. 

IND  =  —2  IND  was  modified,  being  assigned  a  value  3  when  HC  was  re¬ 
called.  Reset  IND  to  its  previous  output  value,  reset  NB,  and 
recall  HC  if  another  circuit  is  wanted. 

IND  '=  —  3  The  input  setting  IND  =  3  is  not  needed  when  the  previous  output 
value  for  IND  was  4.  In  this  case,  nothing  was  done. 

IND  =  -4  NUM  <  m  +  8n  +  20. 

IND  =  -5  P(l)  ^  0  or  P(n  +  1)  #  m. 

IND  =  -6  P(i)  >  P(t  + 1)  for  some  j. 

Remarks. 

(1)  It  is  assumed  that  G  contains  no  loops. 

(2)  Normally,  few  backtracks  are  needed  when  the  number  of  vertices  in  each  Ri  is  small, 
say  10  or  less.  Consequently,  the  setting  NB  =  —  1  is  generally  appropriate  in  such 
cases. 
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Programming.  HC  employs  the  subroutines  HC1,  IPATH,  FUPD,  BUPD,  IUPD,  and 
RARC.  The  search  procedure  in  these  routines  was  written  by  Silvano  Martello  (University 
of  Bologna,  Italy).  The  user  interface  involving  the  variable  IND  was  written  by  A.  H. 
Morris. 

Reference.  Martello,  S.,  “Algorithm  595.  An  Enumerative  Algorithm  for  Finding  Hamilto¬ 
nian  Circuits  in  a  Directed  Graph,”  ACM  Trans.  Math  Software  9  (1983),  pp.  131-138. 
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ERROR  FUNCTION 


For  any  complex  z  the  error  function  is  defined  by 


erf(z)  =  ~^=  f  e  **  dt 
y/“R  Jo 

and  its  complement  by  erfc(z)  =  1  -  erf (2).  The  subroutines  CERF,  CERFC,  DCERF, 
and  DCERFC  are  available  for  computing  erf(z)  and  erfc(z)  when  z  is  complex,  and  the 
functions  ERF,  ERFC,  ERFC1,  DERF,  DERFC,  and  DERFC1  are  available  for  computing 
erf(z)  and  erfc(z)  when  z  is  real.  DCERF,  DCERFC,  DERF,  DERFC,  and  DERFC1  are 
double  precision  routines. 

CALL  CERF(MO,z,tu) 


MO  is  an  integer,  z  a  complex  number,  and  w  a  complex  variable.  When  CERF  is 
called,  w  is  assigned  the  value  erf(z)  if  MO  =  0  and  the  value  erfc(z)  if  MO  ^  0. 

Algorithm.  For  z  =  x  +  iy  where  x  >  0,  if  z  satisfies  \z\  <  1  or  both  of  the  inequalities 
1  <  |z|  <  \/38  and  x2  —  y2  +  .064x2t/2  <  0,  then  the  series 


(1) 

is  used.  If  1  <  Jzj  <  \/Z8  and 


er: 


2  (-1  )nz2n+1 


i(z)  -  _L_  V'  v-1!  J 

ni(2«  +  l) 

x2  —  y2  +  ,064x2y2  >  0  then 


__a  18 


(2) 


erf(z)  =  1  — 


££ _ y'  rn 


is  employed.  An  and  r„  are  the  poles  and  residues  of  the  rational  function  approximation 
for  the  complex  Fresnel  integral  E(z)  given  in  the  reference.  The  error  function  is  related 
to  E(z)  by  erf(z)  =  1  -  iy/2E(-z2)  for  |arg(z)|  <  jt/2.  If  |z|  >  \/38  and  x  >  .01  then  erf(z) 
is  computed  by  the  asymptotic  expansion  erf(z)  =  1  —  1 />(z)  where 


(3) 


#*)  = 


V* 


I  4-  W  1\n1‘3>--(2n~  1) 
*  '  2n^2n-fl 


n>l 


Otherwise,  if  |z|  >  \/38  and  0  <  x  <  .01  then  erf(z)  =  -ip{z)  is  employed.  When  x  <  0 
then  the  relation  erf(— z)  =  — erf(z)  is  applied. 

Programming.  Written  by  Allen  V.  Hershey  and  A.  H.  Morris. 

Reference.  Hershey,  A.  V.,  Approximation  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 
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CALL  CERFC(MO,z,u>) 

MO  is  an  integer,  z  a  complex  number,  and  w  a  complex  variable.  When  CERFC  is 
called,  w  is  assigned  the  value  erfc(z)  if  MO  =  0  or  Re(z)  <  0.  Otherwise,  if  MO  ^  0  and 
Re(z)  >  0  then  w  is  assigned  the  value  ez  erfc(z). 

Precision.  For  MO  ^  0,  Re(tu)  and  Im(u;)  are  accurate  to  within  1  unit  of  the  12th  signifi¬ 
cant  digit  when  |Re(u/)|  >  lO-280  and  Im(tu)  ^0. 

Programming.  CERFC  employs  the  subroutine  CREC  and  functions  EXPARG  and  IPM- 
PAR.  CERFC  was  written  by  Allen  V.  Hershey  and  A.  H.  Morris. 

Reference.  Hershey,  A.  V,  Approximation  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 

ERF(x) 

ERF(x)  =  erf(x)  for  any  real  x. 

Precision.  ERF(x)  is  accurate  to  within  2  units  of  the  14tfc  significant  digit  for  i^O. 
Programmer.  A.  H.  Morris 

Reference.  Cody.  W.  J.,  “Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 

ERFC(x) 

ERFC(x)  =  erfc(x)  for  any  real  x. 

Precision.  If  x  <  3  then  ERFC(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit. 
Otherwise,  if  x  >  3  then  ERFC(z)  is  accurate  to  within  4  units  of  the  14th  significant  digit 
when  ERFC(z)  ^  0. 

Programmer.  A.  H.  Morris 

Reference.  Cody.  W.  J.,  “Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 

ERFCl(IND,x) 

IND  is  an  integer  and  x  a  real  number.  ERFCl(IND,x)  =  erfc(x)  when  IND  =  0,  and 
ERFCl(IND,x)  =  ezerfc(x)  when  IND  ^  0. 

Precision.  If  x  <  3  then  ERFC1(0,  x)  is  accurate  to  within  2  units  of  the  14th"  significant 
digit.  Otherwise,  if  x  >  3  then  ERFCl(0,x)  is  accurate  to  within  4  units  of  the  14th 
significant  digit  when  ERFCl(0,x)  #  0.  If  IND  ±  0  then  ERFCl(IND,x)  is  accurate  to 
within  2  units  of  the  14*^  significant  digit  for  x  >  —  1. 
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Programmer.  A.  H.  Morris 


Reference.  Cody.  W.  J.,  “Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 


CALL  DCERF(MO,i?,  W) 

MO  is  an  integer,  and  Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is 
assumed  that  Z(  1)  and  Z( 2)  are  the  real  and  imaginary  parts  of  a  complex  number  z.  If 
MO  =  0  then  the  double  precision  value  for  w  =  erf(z)  is  computed,  and  if  MO  0  then 
the  double  precision  value  for  w  =  erfc(z)  is  computed.  W (1)  and  W (2)  contain  the  real 
and  imaginary  parts  of  w,  respectively. 


Algorithm.  For  z  —  x  +  iy  where  x  >  0,  if  \z\  <  1  then  (l)  is  used,  and  if  \z  —  2|  <  1  and 
x  <  2  then  the  Taylor  series 

(4)  erfc(z)  =  erfc(a)  +  ~j=e~a3  £  (-l)n.ffn_1(a)(z  -  a)n/n\  (a  =  2) 

V*  n=l 

is  employed.  Here  Hn(a)  are  the  Hermite  polynomials.  If  1  <  \z\  <  2.5  then  (4)  and  the 
Pade  approximation  An(z2)/ Bn(z2)  for  %/n(2z)~1ez  erf(z)  are  used  where 

A0(l)  =  l  A1(z)  =  l+^z 
J  B0(l)  =  l  Bi(z)  =  1  —  §  z 


and  An  and  Bn  satisfy 


(6) 


1 


(4  = 


l  - 


2z 


(4n  +  l)(4n  +  5) 


Bn{z)  + 


4n(4n  +  2)z2 


(4n  —  l)(4n  +  l)2(4n  +  3) 


Bn-i{z ) 


(see  pp.  191,192,  and  422  of  the  reference).  Also,  if  2.5  <  |z|  <  12  then  An(z2)/B„(z2)  and 
the  Pade  approximation  Gn(zi)/Hn(z 2)  for  i/irze*2 erfc(z)  are  employed  where 


(7) 


G0(z)  =  1  Gi(z)  =  2  +  2z 
Ho{z)  =  l  .ffi(z)  =  3  +  2z 


and  Gn  and  Hn  satisfy 


(8)  tfn+i(*)  =  {2z  +  4 n  +  3 )Hn(z)  -  2n(2n  +  1  )Hn-X{z) 

(see  pp.  201  and  422  of  the  reference).  Otherwise,  if  Jz|  >  12  and  x  >  .01  then  the 
asymptotic  expansion  erfc(z)  =  ip(z)  is  used  where  t/?(z)  is  given  by  (3).  Also,  if  |z|  >  12 
and  0  <  x  <  .01  then  erf(z)  =  — t p(z)  is  employed.  When  x  <  0  the  relation  erf(— z)  = 
— erf(z)  is  applied. 

Programming.  DCERF  calls  the  subroutines  ERFCM2,  CDIVID,  and  DCREC.  DCERF 
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and  ERFCM2  were  written  A.  H.  Morris.  The  function  DPMPAR  is  also  used. 

Reference.  Luke,  Yudell  L.,  The  Special  Functions  and  Their  Approximations,  Vol  2, 
Academic  Press,  New  York,  1969. 

CALL  DCERFC(MO,.Z,  W) 

MO  is  an  integer,  and  Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is 
assumed  that  Z(l)  and  Z( 2)  are  the  real  and  imaginary  parts  of  a  complex  number  z. 
If  MO  =  0  or  Re(z)  <  0  then  the  double  precision  value  for  w  =  erfc(z)  is  computed. 
Otherwise,  if  MO  /  0  and  Re(z)  >  0  then  the  double  precision  value  for  w  =  ez  erfc(z)  is 
computed.  W(l)  and  W (2)  contain  the  real  and  imaginary  parts  of  w,  respectively. 

Precision.  For  MO  7^  0  and  Re(z)  >  0,  W(  1)  and  W(2)  are  accurate  to  within  3  units  of 
the  26th  significant  digit  when  W  (2)  7^  0. 

Programming.  DCERFC  employs  the  subroutines  ERFCM2,  DCIVID,  and  DCREC,  and 
functions  DXPARG,  DPMPAR, and  IPMPAR.  DCERFC  and  ERFCM2  were  written  by  A. 
H.  Morris. 

DERF(x) 

The  argument  x  is  a  double  precision  real  number.  DERF(x)  is  the  double  precision 
value  for  erf(x). 

Remark.DERF  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  |x|  <  1  then  the  power  series  corresponding  to  the  Chebyshev  expansion 
given  in  the  SLATEC  library  by  Wayne  Fullerton  (Los  Alamos)  is  used.  The  power  series 
was  obtained  by  A.  H.  Morris.  If  |x|  >  1  then  Chebyshev  expansions  derived  by  J.  L. 
Schonfelder  (University  of  Birmingham,  England)  are  used. 

Precision.  DERF(x)  is  accurate  to  within  2  units  of  the  28tA  significant  digit  for  x  7^  0. 

Programming.  DERF  calls  the  functions  DCSEVL  and  DPMPAR.  DERF  was  written  by 
A.  H.  Morris. 

Reference.  Schonfelder,  J.  L.,  “Chebyshev  Expansions  for  the  Error  and  Related  Func¬ 
tions,”  Math  Comp.  32  (1978),  pp.  1232-1240. 

DERFC(x) 

The  argument  x  is  a  double  precision  real  number.  DERFC(x)  is  the  double  precision 
value  for  erfc(x). 

Remark.  DERFC  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 
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Algorithm.  If  |x|  <  1  then  the  power  series  corresponding  to  the  Chebyshev  expansion 
given  in  the  SLATEC  library  by  Wayne  Fullerton  (Los  Alamos)  is  used.  The  power  series 
was  obtained  by  A.  H.  Morris.  If  |x|  >  1  then  Chebyshev  expansions  derived  by  J.  L. 
Schonfelder  (University  of  Birmingham,  England)  and  the  standard  asymptotic  expansion 
for  erfc(x)  are  used. 

Precision.  DERFC(x)  is  accurate  to  within  2  units  of  the  28th  significant  digit  for  x  <  2. 

Programming.  DERFC  calls  the  functions  DCSELV  and  DPMPAR.  DERFC  was  written 
by  A.  H.  Morris. 

Reference.  Schonfelder,  J.  L.,  “Chebyshev  Expansions  for  the  Error  and  Related  Func¬ 
tions,”  Math  Comp.  32  (1978),  pp.  1232-1240. 

DERFC1(IND,  x) 

IND  is  an  integer  and  x  a  double  precision  real  number.  DERFCl(IND,x)  is  the  dou¬ 
ble  precision  value  for  erfc(x)  when  IND  =  0,  and  DERFCl(IND,x)  is  the  double  precision 
value  for  ezerfc(x)  when  IND  0. 

Remark.  DERFC1  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DERFCl(IND,x)  is  accurate  to  within  2  units  of  the  28th  significant  digit  when 
IND  =  0  and  x  <  2,  and  when  IND  ^  0  and  x  >  —  1 

Programming.  DERFC1  calls  the  functions  DCSEVL  and  DPMPAR.  DERFC1  was  written 
by  A.  H.  Morris. 
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INVERSE  ERROR  FUNCTION 


For  any  0  <  x  <  1,  the  following  function  is  available  for  obtaining  the  value  u;  >  0  for 
which  erf(u/)  =  x. 

ERFINV(x,  y) 

It  is  assumed  that  0  <  x  <  1  and  y  =  1  -  x.  If  y  ^  0  then  ERFINV(x,  y)  =  w  where 
w  >  0  and  erf(tu)  =  x.  Otherwise,  if  y  =  0  then  ERFINV(x,y)  =  the  largest  positive 
number  in  the  floating  arithmetic  being  used. 

Error  Return.  ERFINV(x,  y)  <  0  if  x  <  0,  y  <  0 ,  or  x  +  y  ^  1. 

Precision.  For  x  ^  0  and  y  ^  0,  ERFINV(x,y)  is  accurate  to  within  3  units  of  the  14th 
significant  digit. 

Programming.  ERFINV  was  written  by  Armido  R.  DiDonato  and  modified  by  A.  H.  Mor¬ 
ris.  The  function  SPMPAR  is  used. 

Reference.  Blair,  J.  M.,  Edwards,  C.  A.,  and  Johnson,  J.  H.,  “Rational  Chebyshev  Approx¬ 
imations  for  the  Inverse  of  the  Error  Function,”  Math  Comp.  30  (1976),  pp.  827-830. 
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NORMAL  PROBABILITY  DISTRIBUTION  FUNCTION 


For  any  real  x ,  the  normal  probability  distribution  function  P(x)  (of  mean  0  and 
variance  1)  is  defined  by 


dt 


and  its  complement  by  Q(x)  =  1  -  P(x).  The  following  function  is  available  for  computing 
P(x )  and  Q(i). 

PNDF(x,IND) 


IND  is  an  integer  and  x  a  real  number.  If  IND  =  0  then 

P{x)  if  x  >  —  8 


PNDF(z,0)  =  <  p'(*)  . 


*(*) 


if  x  <  -8 


where  P'(x)  is  the  derivative  of  P(x).  Otherwise,  if  IND  ^  0  then 

Q{x)  if  x  <  8 


PNDF(x,IND)  =  <  Q'(x) 


Q{x) 


if  x  >  8 


where  Q'( x)  is  the  derivative  of  Q(x). 

Algorithm.  The  identities  P(x)  =  \  erfc(-x/\/2)  and  Q(x)  =  \edc{x/y/2)  are  used. 
Programming.  PNDF  calls  the  function  ERFC1.  PNDF  was  written  by  A.H.  Morris. 
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INVERSE  NORMAL  PROBABILITY  DISTRIBUTION  FUNCTION 


For  any  real  u/,  the  normal  probability  distribution  function  P(w)  (of  mean  0  and 
variance  1)  is  defined  by 


P(w)  =  — L  r  e~t2/2  dt 


and  its  complement  by  Q(u/)  =  1  —  P( w).  For  any  0  <  p  <  1  and  q  =  1  —  p,  the  following 
function  is  available  for  obtaining  the  value  w  for  which  -P(tu)  =  p  and  Q(tn)  =  q. 


PNINV(p,  q,  z,  IERR) 

It  is  assumed  that  0<p<l,g  =  l  —  p,  and  z  =  p  —  q.  IERR  is  a  variable.  When 
PNINV  is  used,  if  no  input  errors  are  detected  then  IERR  is  set  to  0.  If  p  ^  0  and  q  ^  0 
then  PNINV(p,<7, 2, IERR)  =  w  where  -P(w)  =  p  and  Q(tn)  =  q.  Otherwise, 


PNINV(p,  g,  z,IERR)  =  |  *max  ° 

{  Zmax  if  q  =  0 

where  zmax  is  the  largest  positive  number  in  the  floating  arithmetic  being  used. 

Error  Return.  If  an  input  error  is  detected,  then  IERR  is  set  to  one  of  the  following  values: 
IERR  =  1  Either  p  <  0,  q  <  0,  or  p  +  q  ^  1. 

IERR  =2  z  ^  p  —  q 

In  these  cases,  PNINV  is  assigned  the  value  0. 

Algorithm.  For  y  >  0,  let  y  =  erf-1(i)  when  x  =  erf(y).  If  P(tu)  =  p  then  the  identities 


J  —y/2  erf  X(1  —  2p)  if  0  <  p  <  1/2 
1  \fL  erf_1(2p  -  1)  if  1  >  p  >  1/2 


are  applied. 

Precision.  For  p  /  0,g  /  0,  and  z  /  0  PNINV  is  accurate  to  within  3  units  of  the  14th 
significant  digit. 

Programming.  PNINV  employs  the  functions  ERFINV  and  SPMPAR.  PNINV  was  written 
by  Armido  R.  DiDonato. 
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DAWSON'S  INTEGRAL 


For  any  real  x,  Dawson’s  integral  is  defined  by 

F(x)  =  e~x  f  e*3  dt. 

Jo 

The  following  function  is  available  for  computing  F(x). 

DAW(x) 

DAW(x)  =  F(x)  for  any  real  x. 

Precision.  DAW(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit  for  x^O. 

Programming.  DAW  belongs  to  the  FUNPACK  package  of  subroutines  developed  at  Ar- 
gonne  National  Laboratory.  The  function  was  modified  by  A.  H.  Morris. 

Reference.  Cody,  W.  J.,  Paciorek,  K.  A.,  and  Tacher,  H.  C.,  “Chebyshev  Approximations 
for  Dawson’s  Integral,”  Math  Comp.  24  (1970),  pp.  171-178. 
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COMPLEX  FRESNEL  INTEGRAL 


For  any  complex  z  not  on  the  positive  real  axis  the  complex  Fresnel  integral  E{z) 
be  defined  by 


can 


Here  it  is  assumed  that  0  <  arg(z)  <  2?r  and  arg(v/i)  =1/2  arg(z).  E(z )  can  be  extended 
to  the  positive  real  axis  by  letting  0  <  arg(z)  <  2tt.  Then  erf(z)  =  1  -  iy/2E(-z2)  for 
-jt/2  <  arg(z)  <  it  j 2  where  erf(z)  is  the  error  function  and  arg(— z2)  =  jr  +  2  arg(z).  The 
following  subroutine  is  available  for  computing  E(z). 


CALL  CFRNLI(MO,  z,  w) 


MO  is  an  integer,  z  a  complex  number,  and  w  a  complex  variable.  When  CFRNLI  is 
called,  w  is  assigned  the  value  E(z)  if  MO  =  0  and  the  value  e~zE(z )  if  MO  ^  0. 


Algorithm.  If  z  =  x  +  ty  satisfies  \z\  <  1  or  both  of  the  inequalities  1  <  \z\  <  38  and 
— x  +  .016y2  <  0,  then  the  series 


E(z)  =  — l—  +  y/2z/x  Z - — 

V2  n!(2n  +  1) 


is  used.  If  1  <  \z\  <  38  and  —  x  +  ,016y2  >  0  then 


E(z)  = 


r  n 

z-  8n 


is  employed.  If  \z\  >  38  and  Im  \j2zjit  >  .008  then  E(z)  is  computed  by  the  asymptotic 
expansion  E(z)  =  ip(z)  where 


1  _i_  V  1 ' 3 ' '  ‘  (2n  ~  !) 

V  (2z)n 

r»>l  v  ‘  J 

Otherwise,  if  \z\  >  38  and  Im  \j2zjit  <  .008  then  E(z)  =  -j/\/2  +  t/>(z)  is  employed. 

Precision.  For  MO  /  0,  Re(tn)  and  Im(tt;)  are  accurate  to  within  1  unit  of  the  12th 
significant  digit  when  Re(ti/)  and  Im(to)  are  nonzero. 


Programming.  CFRNLI  employs  the  functions  CPABS,  EXPARG,  and  IPMPAR.  CFRNLI 
was  written  by  Allen  V.  Hershey  and  A.  H.  Morris. 

Reference.  Hershey,  A.  V.,  Approximation  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 
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REAL  FRESNEL  INTEGRALS 


For  any  complex  2  the  Fresnel  integrals  C(z)  and  S(z)  can  be  defined  by 

z)=l  “’(I*1)* 

sw=J0 

The  following  subroutine  is  available  for  computing  C{z)  and  5(2)  when  2  is  real. 

CALL  FRNL(x,C,  S) 

The  argument  x  may  be  any  real  number.  C  and  S  are  variables.  When  FRNL  is 
called  C  is  assigned  the  value  C( x)  and  S  is  assigned  the  value  S(x). 

Algorithm.  If  0  <  x  <  1.65  then  x~1C(x)  and  x~zS(x )  are  computed  by  minimax  polyno¬ 
mial  approximations.  Otherwise,  if  x  >  1.65  then  the  relations 

Cix)  +  /(* )  sin|a:2  -  g{x)  cos|z2 
s(x )  =\  ~  f(x)  cos|z2  -  g(x)  sin|x2 

are  invoked.  For  1.65  <  x  <  6,  xf(x)  and  x3g(x)  are  computed  by  rational  minimax 
approximations.  Otherwise,  for  x  >  6  the  auxiliary  functions  f(x)  and  g(x)  are  computed 
by  the  asymptotic  expansions: 


t  =  l  v  * 

9K  ]  ]  (jtz2)2*+i 


Here  m  =  5.  If  x  <  0  then  the  relations  C(-x )  =  -C{x)  and  S’f-a:)  =  -S(x )  are  applied. 


Precision.  If  |z|  <  1.65  then  FRNL  is  accurate  to  within  3  units  of  the  14th  significant 
digit.  Otherwise,  if  |x|  >  1.65  then  FRNL  is  accurate  to  within  1  unit  of  the  14th  significant 
digit. 


Programming.  FRNL  calls  the  functions  SPMPAR  and  IPMPAR.  FRNL  was  written  by 
A.  H.  Morris. 
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EXPONENTIAL  INTEGRAL  FUNCTION 


For  any  complex  0  not  on  the  positive  real  axis  the  exponential  integral  function 
Ei(z)  is  defined  by 

f*  €t 

Ei (*)  =  J  Jjdt. 

Ei(z)  is  an  analytic  function.  If  z  is  replaced  by  — z  and  i  by  — t  we  obtain  the  related 
function 

r°°  e-t 

Ei{z)  =  -Ei(-z)  =  J  — dt 

which  is  defined  for  all  z  ^  0  not  on  the  negative  real  axis.  It  can  be  verified  that 


Ei(z)  =  v  +  ln(-z)  +  Yi  — 


n=  1 


n! 


everywhere  in  the  plane  cut  along  the  positive  real  axis  where  v  is  the  Euler  constant.  Thus, 
the  values  of  Ei(x)  on  the  upper  and  lower  edges  of  the  cut  are 

Ei(x  ±  t‘0)  =  ei(x)  ni 

where  ei(x)  is  the  real  function  defined  by 


ei(x)  =  v  +  In  x  +  Y' - - 

x  J  ^  n-n! 


n=  1 


for  x  >  0.  The  function  ei(x),  also  known  as  the  exponential  integral  function,  has  a  zero 
at  the  point  xo  =  .37250  74107  81367.  Ei(z)  may  be  computed  by  the  subroutine  CEXPLI 
when  z  is  complex,  and  Ei (z)  and  ei(z)  may  be  computed  by  the  subroutine  EXPLI  and 
functions  DEI  and  DEI1  when  z  is  real.  DEI  and  DEI1  are  double  precision  functions. 

CALL  CEXPLI(MO,z,to) 

MO  is  an  integer,  z^O  a  complex  number,  and  w  a  complex  variable.  When  CEXPLI 
is  called,  w  is  assigned  the  value  Ei(z)  if  MO  =  0  and  the  value  e~a  Ei(z)  if  MO  ^  0. 

Remark.  If  z  is  a  positive  real  number  and  MO  =  0  then  w  =  ei(z)  +zrt. 


Precision.  If  MO  =  0  then  Re(t«)  and  Im(to)  are  accurate  to  within  2  units  of  the  12th 
significant  digit  when  z  is  not  near  a  zero  of  Re(Ei(z))  or  Im(Ei(z)). 

Programming.  CEXPLI  employs  the  functions  CPABS  and  SPMPAR.  CEXPLI  was  ini¬ 
tially  written  by  Allen  V.  Hershey,  and  later  rewritten  by  A.  H.  Morris. 


Reference.  Hershey,  A.  V.,  Approximations  of  Functions  by  Sets  of  Poles ,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 
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CALL  EXPLI(MO,x,t//,IERR) 

MO  may  have  the  values  1,2,  or  3.  The  argument  a:  is  a  nonzero  real  number  and  tv 
a  real  variable.  When  EXPLI  is  called,  if  MO  =  1  then  tv  is  assigned  the  value  Ei(x)  for 
x  <  0  and  the  value  ei(x)  for  x  >  0.  If  MO  =  2  then  it  is  assumed  that  x  >  0.  In  this  case 
tv  is  assigned  the  value  Ei(x).  Otherwise,  if  MO  =  3  then  to  is  assigned  the  value  e-xEi(x) 
for  x  <  0  and  the  value  e~x  ei(x)  for  x  >  0. 

Error  return.  IERR  is  a  variable  that  reports  the  status  of  the  results.  If  the  requested 
value  tv  is  obtained  then  IERR  is  set  to  0.  Otherwise,  IERR  is  assigned  one  of  the  following 
values: 

IERR  =  1  Underflow  occurs.  In  this  case  tv  =  0. 

IERR  —  2  Overflow  occurs. 

IERR  =  3  (Input  error)  x  =  0. 

IERR  =  4  (Input  error)  MO  =  2  and  x  <  0. 

The  variable  tv  is  not  defined  when  IERR  >2. 

Algorithm.  If  MO  2  and  4  <  x  <  8,  then  the  Chebyshev  expansion  in  the  SLATEC 
library  obtained  by  Wayne  Fullerton  (Los  Alamos)  is  used.  The  remaining  approximations 
employed  are  from  the  references. 

Precision.  If  MO  ±  2  and  x  >  0,  then  tv  is  accurate  to  within  4  units  of  the  14th  significant 
digit  when  tv  ^  0.  Otherwise,  tv  is  accurate  to  within  3  units  of  the  14th  significant  digit 
when  tv  0. 

Programming.  EXPLI  employs  the  functions  ALNREL,  CSEVL,  EXPARG,  and  IPMPAR. 
EXPLI  was  written  at  Argonne  National  Laboratory  for  the  FUNPACK  package  of  special 
function  subroutines.  EXPLI  was  modified  by  A.  H.  Morris. 

References.. 

(1)  Cody,  W.  J.  and  Thacher,  H.  C.,  “Rational  Chebyshev  Approximations  for  the  Expo¬ 
nential  Integral  Ei(x),”  Math  Comp.  22  (1968),  pp.  641-649. 

(2)  _ _ ,  “Chebyshev  Approximations  for  the  Exponential  Integral  Ei(x) ,”  Math 

Comp.  23  (1969),  pp.  289-303. 

DEI(x) 

The  argument  x  ^  0  is  a  double  precision  number.  DEI(x)  is  the  double  precision  value 
for  Ei(x)  when  x  <  0,  and  the  double  precision  value  for  ei(x)  when  x  >  0. 

Remark.  DEI  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  .35  <  x  <  .4  then  the  Taylor  series  expansion  of  ei(x)  around  xo  is  used. 
This  expansion  was  obtained  by  A.  H.  Morris.  If  |x|  >  90  then  the  standard  asymptotic 
expansion  for  Ei  and  ei  is  applied.  Otherwise,  the  Chebyshev  expansions  in  the  SLATEC 
library  obtained  by  Wayne  Fullerton  (Los  Alamos)  are  used. 
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Programming.  DEI  employs  the  functions  DE1E  and  DEIO.  These  functions  were  written 
by  A.  H.  Morris.  The  functions  DCSEVL  and  DPMPAR  are  also  used. 

DEIl(x) 

The  argument  i  ^  0  is  a  double  precision  number.  DEIl(x)  is  the  double  precision 
value  for  e~x  Ei(x)  when  x  <  0,  and  the  double  precision  value  for  e~x  ei(x)  when  x  >  0. 

Remark.DEIl  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  .35  <  x  <  .4  then  the  Taylor  series  expansion  of  ei(x)  around  x0  is  used. 
This  expansion  was  obtained  by  A.  H.  Morris.  If  |x|  >  90  then  the  standard  asymptotic 
expansion  for  Ei  and  ei  is  applied.  Otherwise,  the  Chebyshev  expansions  in  the  SLATEC 
library  obtained  by  Wayne  Fullerton  (Los  Alamos)  are  used. 

Precision.  DEIl(x)  is  accurate  to  within  4  units  of  the  28th  significant  digit  when  DEIl(x) 

7^0. 

Programming.  DEI1  employs  the  functions  DE1E  and  DEIO.  These  functions  were  written 
by  A.  H.  Morris.  The  functions  DCSEVL  and  DPMPAR  are  also  used. 
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SINE  AND  COSINE  INTEGRAL  FUNCTIONS 


For  any  complex  z  the  sine  integral  and  cosine  integral  functions  Si(,z)  and  Cin(z)  are 
defined  by 

SiW  =  dt 

CmW  =  f  -  ™  ‘  dt. 

These  are  entire  functions.  The  following  functions  are  available  for  computing  Si(z)  and 
Cin(2)  when  z  is  real. 

Sl(x) 

SI(x)  =  Si(x)  for  all  real  x. 

Precision.  SI  is  accurate  to  within  2  units  of  the  14th  significant  digit. 

Programming.  SI  calls  the  function  SPMPAR.  SI  was  written  by  Donald  E.  Amos  and 
Sharon  L.  Daniel  (Sandia  Laboratories),  and  modified  by  A.  H.  Morris. 

CIN(i) 

CIN(i)  =  Cin(x)  for  all  real  x. 

Precision.  CIN  is  accurate  to  within  2  units  of  the  14th  significant  digit. 

Programming.  CIN  calls  the  function  SPMPAR.  CIN  was  written  by  Donald  E.  Amos  and 
Sharon  L.  Daniel  (Sandia  Laboratories),  and  modified  by  A.  H.  Morris. 
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DILOGARITHM  FUNCTION 


For  any  complex  z  where  |arg(l  +  z) j  <  jr,  the  dilogarithm  function  L(z)  may  be 
defined  by 

£W=/;mi±o*. 

L(z )  is  real-valued  for  any  real  z  >  — 1,  and  —1  is  a  branch  point.  L(z)  can  be  extended  to 
the  negative  real  axis  from  -oo  to  -1  by  letting  —  ir  <  arg(l  +  z)  <  n.  Then  for  any  real 
x  <  —  1 

L{x )  =  -7r2/6  +  f  ^  dt  +  r>ln(— x)  (t  =  V^T). 

Ji  t 

The  function  CLI  is  available  for  computing  L(z)  when  z  is  complex,  and  the  function  ALI 
is  available  for  computing  the  real  part  of  L(z)  when  z  is  real. 

CLI(z) 

CLI  is  a  complex-valued  function  where  CLI(z)  =  L(z)  for  all  complex  z.  CLI  must 
be  declared  in  the  calling  program  to  be  of  type  COMPLEX. 

Algorithm.  For  \z\  <  1/2  the  Maclaurin  series 

m 

n>l 

is  used.  If  \z\  >  3  then 

(2)  L(z)  =  jt2/6  -  L{ljz)  +  l/21n2z 
is  applied,  and  if  0  <  \z  +  1|  <  1/2  then 

(3)  L(z)  =  -tt2/6  -  L(— 1  -  z)  +  ln(— z)  ln(l  +  z) 


is  applied.  Otherwise, 


(4) 


(Debye  Function) 


=  -u> + m2/4  - 

n>l 


B2nw2n+1 

(2n  +  l)! 


u?j  <  2t 


is  used  where  w  =  —  ln(l  +  z)  and  B2n  are  the  Bernoulli  numbers  B2  =  1/6,  B\  = 
—1/30, - In  (3)  we  note  that  ln(-z)ln(l  +  z)  — ►  0  when  z  — ^  —1. 


Programming.  CLI  is  a  modification  by  A.  H.  Morris  of  the  subroutine  CLGMCI,  written 
by  Allen  V.  Hershey. 
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Reference.  Hershey,  A.  V.,  Approximation  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 

ALI(x) 

ALI(x)  =  Re[L(x)|  for  all  real  x. 

Algorithm.  Rational  minimax  approximations  are  used  when  — 1/2  <  x  <  1.  If  x  >  1  then 
(2)  is  applied,  and  if  — 2  <  x  <  — 1  or  — 1  <  x  <  —1/2  then  (3)  is  applied.  Otherwise,  if 
x  <  —2  then 

Re[L(x)]  =  — x2/3  -  L(l-/x)  +  l/21n2(— x) 

(which  follows  from  (2))  is  used  except  when  —26.63  <  x  <  —6.97.  Since  Re[L(x0)]  =  0  for 
xo  =  —12.59517  . . . ,  the  Taylor  series  of  Re[L(x)]  around  xo  is  used  when  —14  <  x  <  —11.1. 
Otherwise,  if  —11.1  <  x  <  —6.97  or  —26.63  <  x  <  —14  then  rational  minimax  approxima¬ 
tions  are  employed. 

Precision.  ALI(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit  when  x  >  0. 
Otherwise,  if  x  <  0  then  ALI(x)  is  accurate  to  within  4  units  of  the  14th  significant  digit 
when  ALI(x)  ^  0. 

Programmer.  A.  H.  Morris 

Reference.  Morris,  Robert,  “The  Dilogarithm  Function  of  a  Real  Argument,”  Math. 
Comp.  33  (1979),  pp.  778-787. 
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GAMMA  FUNCTION 


For  any  complex  z  ^  0,  —  1,  —2,  . . .  the  gamma  function  can  be  defined  by 

(~l)n  1 


r(«)  =  E  1  +  f-1 

h  n!  *  +  "  A 


—  1  —t 


e  1  dt. 


Then  f(z)  is  a  meromorphic  function  having  simple  poles  at  0,  —1,  —2,  . . .  ,and 


T(z)=  f°°  tz~1e~i  dt 

Jo 

for  Re(z)  >  0.  Also  T(z)  ^  0  for  all  z.  The  subroutines  CGAMMA  and  DCGAMA  are 
available  for  computing  T(z)  and  In  r(z)  when  z  is  complex,  and  the  functions  GAMMA, 
GAMLN,  DGAMMA,  and  DGAMLN  are  available  for  computing  T(z)  and  In  T(z)  when  z 
is  real.  DCGAMA,  DGAMMA,  and  DGAMLN  are  double  precision  procedures. 

CALL  CGAMMA(MO,z,  tu) 

MO  is  an  integer,  z  a  complex  number  satisfying  z  ^  0,  —  1,  —  2,  . . . ,  and  w  a  complex 
variable.  When  CGAMMA  is  called,  w  is  assigned  the  value  r(z)  if  MO  =  0  and  the  value 
In  T(z)  if  MO  t^O. 

Error  return.  If  z  —  0,  —  1,  —2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  for  In T(z)  to  be 
computed,  then  w  is  assigned  the  value  0. 

Programming.  CGAMMA  calls  the  functions  REXP,  SPMPAR,  and  IPMPAR.  CGAMMA 
was  written  by  A.  H.  Morris. 

References. 

(1)  Kuki,  Hirondo,  “Complex  Gamma  Function  with  Error  Control,”  Comm.  ACM  15 
(1972),  pp.  262-267. 

(2)  Spira,  Robert,  “Calculation  of  the  Gamma  Function  by  Stirling’s  Formula,”  Math 
Comp.  25  (1971),  pp.  317-322. 


GAMMA(x) 

The  argument  x  is  areal  number.  If  T(*)  can  be  computed  then  GAMMA(i)  is  assigned 
the  value  r(z).  Otherwise,  if  T(x)  cannot  be  computed,  then  GAMMA(z)  is  set  to  0. 

Algorithm.  If  |x|  <  15  then  x  is  reduced  to  the  interval  [1,2)  by  T(a  +  1)  =  aT(a),  and  a 
rational  minimax  approximation  is  employed.  If  x  <  — 15  then 


(1) 


(-l)"+1ir 

sin(»rA)|x|r(|x|) 
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is  applied.  Here  |x|  =  n  +  A  where  n  is  the  largest  integer  less  than  |x|.  For  x  >  15 
(2)  lnT(x)  =  (x  -  1/2)  ln  x  -  x  +  i  ln(2jr)  +  A(x) 

is  computed  where  A(x)  is  a  minimax  approximation.  The  function  A(x)  is  evaluated  in 
single  precision,  and  a  double  precision  value  is  obtained  for  lnx.  This  yields  a  double 
precision  value  for  lnT(x).  If  lnT(x)  =  a +  5  where  a  is  the  leading  portion  of  lnT(x),  then 
T(x)  is  set  to  e“(l  +  5).  This  is  permissible  since  1  +  5  is  the  portion  of  the  Taylor  series 
expansion  for  es  that  is  significant. 

The  logarithm  lnx  is  evaluated  as  follows:  Let  n  be  the  largest  integer  less  than  or 
equal  to  x,  and  let  t  =  (x  —  n)/(x  +  n).  Then  x  =  n(l  +  i)/(  1  —  t)  so  that  lnx  = 
lnn  +  ln[(l  +  t)/(l  —  t)].  Also  0  <  t  <  l/(2n).  The  function  In  [(l  +  t)/(l  —  t)]  is  computed 
by  a  polynomial  minimax  approximation  in  single  precision,  and  the  value  In  n  is  stored  in 
double  precision. 

Precision.  If  0  <  x  <  2  then  GAMMA(x)  is  accurate  to  within  2  units  of  the  14th  significant 
digit.  If  x  >  2  then  GAMMA(x)  is  accurate  to  within  3  units  of  the  14th  significant  digit. 
Otherwise,  GAMMA(x)  is  accurate  to  within  5  units  of  the  14th  significant  digit. 

Programming.  GAMMA  calls  the  functions  GLOG  and  EXPARG.  These  functions  were 
written  by  A.  H.  Morris.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

GAMLN(x) 

GAMLN(x)  =  lnP(x)  for  all  positive  real  x. 

Algorithm.  See  p.  379  and  appendix  D  of  the  reference. 

Precision.  GAMLN(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit  when 
GAMLN(x)  #0. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programming.  GAMLN  calls  the  function  GAMLN1.  These  functions  were  written  by 
A.  H.  Morris. 

CALL  DCGAMA(MO,£,vn 

MO  is  an  integer,  and  Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is 
assumed  that  £(1)  and  Z( 2)  are  the  real  and  imaginary  parts  of  a  complex  number  z.  If 
MO  =  0  then  the  double  precision  value  for  w  =  T(z)  is  computed.  Otherwise,  if  MO  ^  0 
then  the  double  precision  value  for  w  =  lnr(z)  is  computed.  W  (1)  and  W  (2)  contain  the 
real  and  imaginary  parts  of  to,  respectively. 

Error  Return.  If  z  =  0,  —  1,  —  2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  for  lnT(z)  to  be 
computed,  then  W (l)  and  W (2)  are  assigned  the  value  0. 
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Programming.  DCGAMA  calls  the  functions  DREXP,DPMPAR,  and  IPMPAR.  DCGAMA 
was  written  by  A.  H.  Morris. 

References. 

(1)  Kuki,  Hirondo,  “Complex  Gamma  Function  with  Error  Control,”  Comm.  ACM  15 
(1972),  pp.  262-267. 

(2)  Spira,  Robert,  “Calculation  of  the  Gamma  Function  by  Stirling’s  Formula,”  Mat h 
Comp.  25  (1971),  pp.  317-322. 

DGAMMA(i) 

The  argument  x  is  a  double  precision  real  number.  If  T(x)  can  be  computed  then 
DGAMMA(i)  is  the  double  precision  value  for  T(x).  Otherwise,  if  T(x)  cannot  be  com¬ 
puted,  then  DGAMMA(x)  is  set  to  0. 

Remark.  DGAMMA  must  be  declared  in  calling  program  to  be  of  type  DOUBLE  PRECI¬ 
SION. 

Algorithm.  If  |x|  <  20  then  x  is  reduced  to  the  interval  [1,2)  by  T(a  +  1)  =  ar(a),  and 
the  Chebyshev  expansion  in  the  SLATEC  library  given  by  Wayne  Fullerton  (Los  Alamos) 
is  used.  If  x  <  -20  then  (1)  is  applied,  and  if  x  >  20  then  (2)  is  used.  A(x)  is  computed  by 
the  power  series  corresponding  to  the  Chebyshev  expansion  in  the  SLATEC  library  given 
by  Wayne  Fullerton.  The  power  series  was  obtained  by  A.  H.  Morris. 

Precision.  If  0  <  x  <  2  then  DGAMMA(x)  is  accurate  to  within  1  unit  of  the  28th  signifi¬ 
cant  digit.  Otherwise,  if  x  >  2  then  DGAMMA(x)  is  accurate  to  within  1  unit  of  the  25th 
significant  digit. 

Programming.  DGAMMA  calls  the  functions  DCSEVL,  DPDEL,  and  DXPARG.  These 
functions  were  written  by  A.  H.  Morris.  The  functions  DPMPAR  and  IPMPAR  are  also 
used. 


DGAMLN(x) 

The  argument  x  is  a  double  precision  positive  real  number.  DGAMLN(x)  is  the  double 
precision  value  for  In  T(x). 

Remark.  DGAMLN  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Algorithm.  If  .5  <  x  <  2.5  then  the  Taylor  series  for  1/T(1  +  a)  is  used,  and  if  x  >  10 
then  (2)  is  applied.  A(x)  is  computed  by  the  power  series  corresponding  to  the  Chebyshev 
expansion  in  the  SLATEC  library  given  by  Wayne  Fullerton  (Los  Alamos).  The  power 
series  was  obtained  by  A.  H.  Morris. 
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Precision.  DGAMLN(x)  is  accurate  to  within  2  units  of  the  28th  significant  digit  when 
DGAMLN(x)  ^  0. 

Programming.  DGAMLN  calls  the  functions  DPDEL,  DGMLN1,  and  DLNREL.  These 
functions  were  written  by  A.  H.  Morris.  The  function  DPMPAR  is  also  used. 
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DIGAMMA  FUNCTION 


For  any  complex  z  ^0,  — 1,  -2,  . . .  the  digamma  (or  psi)  function  t/>(z)  is  defined  by 

^(z)  =  r'(z)/r(z) 

where  T(z)  is  the  gamma  function.  For  real  x  >  0,rp(x)  is  an  increasing  function  having  a 
zero  at  the  point  x$  =  1.4616  32144  96836.  The  subroutines  CPSI  and  DCPSI  are  available 
for  computing  ip(z)  when  z  is  complex,  and  the  functions  PSI  and  DPSI  are  available  for 
computing  rp(z)  when  z  is  real.  DCPSI  and  DPSI  are  double  precision  procedures. 

CALL  CPSI(z,u>) 

The  argument  z  is  a  complex  number  satisfying  z  ^  0,  —1,  -2,  . . . ,  and  w  is  a  complex 
variable.  When  CPSI  is  called,  w  is  assigned  the  value  t /’(z). 

Error  Return.  If  z  =  0,  -1,  -2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  for  ip(z)  to  be 
computed,  then  w  is  assigned  the  value  0. 


Algorithm.  If  z  =  x  +  jy  satisfies  x  >  0  and  |z|  >  6,  then  the  asymptotic  expansion 


(1) 


V>(z)  =lnz-i-  -  ^ 


m 

2z  ^—1  2mzSm 

m=l 


is  employed.  Otherwise,  if  x  >  0  then  the  smallest  nonnegative  integer  n  is  found  for  which 
|z  +  n|  >6,  and  the  relation 


n—  1 


Hz)  =  ~  S  7T7  +  ^(z  +  n) 


is  applied.  When  x  <  0  then 

(2)  rjj(z)  =  V>(1  —  z)  —  jrcot(jrz) 

is  also  used. 

Programming.  CPSI  calls  the  functions  REXP,  SPMPAR,  and  IPMPAR.  CPSI  was  written 
by  A.  H.  Morris. 

PSI(z) 

The  argument  a;  is  a  real  number.  If  ip(x)  can  be  computed  then  PSI(x)  is  assigned 
the  value  V >{x )■  Otherwise,  if  rp(x)  cannot  be  computed,  then  PSI(x)  is  set  to  0. 

Precision.  If  x  >  0  then  PSI(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit 
when  PSI(x)  0. 
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Programming.  PSI  calls  the  functions  SPMPAR  and  IPMPAR.  PSI  was  written  at  Argonne 
National  Laboratory  for  the  FUNPACK  package  of  special  function  subroutines.  PSI  was 
modified  by  A.  H.  Morris. 

Reference.  Cody,  W.  J.,  Strecok,  A.  J.,  and  Thacher,  H.  C.,  “Chebyshev  Approximations 
for  the  Psi  Function,”  Math  Comp.  27  (1973),  pp.  123-127. 

CALL  DCPSI(Z, W) 

Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is  assumed  that  Z(  1)  and  Z( 2) 
are  the  real  and  imaginary  parts  of  a  complex  number  z.  When  DCPSI  is  called  the  double 
precision  value  for  w  —  ip(z)  is  computed.  W (1)  and  W (2)  contain  the  real  and  imaginary 
parts  of  w,  respectively. 

Error  Return.  If  z  =  0,  —1,  —2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  for  ip(z)  to  be 
computed,  then  W(  1)  and  W(2)  are  assigned  the  value  0. 

Programming.  DCPSI  calls  the  functions  DREXP,  DPMPAR,  and  IPMPAR.  DCPSI  was 
written  by  A.  H.  Morris. 

DPSI(x) 

The  argument  a:  is  a  double  precision  real  number.  If  rp(x)  can  be  computed  then 
DPSI(x)  is  the  double  precision  value  for  t/»(x).  Otherwise,  if  t/>(x)  cannot  be  computed, 
then  DPSI(x)  is  set  to  0. 

Remark.DPSI  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  |x|  <  10  then  x  is  reduced  to  the  interval  [1,2)  by  %j){a  +  1)  =  £  +  and 
the  Chebyshev  expansion  in  the  SLATEC  library  given  by  Wayne  Fullerton  (Los  Alamos) 
is  used  when  |x  —  Xo|  >  2  •  10~2.  Otherwise,  if  |x  —  xo|  <  2  •  10-2  then  the  Taylor  series 
around  the  zero  xo  is  used.  The  coefficients  for  the  Taylor  series  were  obtained  by  A.  H. 
Morris.  If  x  <  —10  then  (2)  is  applied,  and  if  x  >  10  then  t/>(x)  —  In  x  is  computed  by  the 
power  series  corresponding  to  the  Chebyshev  expansion  in  the  SLATEC  library  given  by 
Wayne  Fullerton.  The  power  series  was  obtained  by  A.  H.  Morris. 

Precision.  If0<x<lorx>2  then  DPSI(x)  is  accurate  to  within  2  units  of  the  28th 
significant  digit.  Otherwise,  if  1  <  x  <  2  then  DPSI(x)  is  accurate  to  within  5  units  of  the 
28th  significant  digit  when  DPSI(x)  ^  0. 

Programming.  DPSI  calls  the  functions  DCSEVL,  DPSI0,  DPMPAR,  and  IPMPAR.  DPSI 
was  written  by  A.  H.  Morris. 
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LOGARITHM  OF  THE  BETA  FUNCTION 


For  a,b  >  0  the  beta  function  B(a,b)  can  be  defined  by 

B(a,6)  =  f1 
Jo 

From  this  it  follows  that  B(a,b )  =  r(a)r(6)/r(a  +  b )  where  T(a)  is  the  gamma  function. 
The  functions  BETALN  and  DBETLN  are  available  for  computing  In  B(a,b).  DBETLN  is 
a  double  precision  function. 

BETALNM) 

BETALN(a,  6)  =  In  B(a,b }  for  a,b  >  0. 

Algorithm.  See  pages  19-21  of  the  reference. 

Precision.  BETALN(a,  b)  is  accurate  to  within  4  units  of  the  14th  significant  digit  when 
a,i»  >  1  and  BETALN(a, b)  ^  0.  In  particular,  when  a,b  >  15,  BETALN(a,6)  is  accurate 
to  within  2  units  of  the  14th  significant  digit. 

Programming.  BETALN  employs  the  functions  ALNREL,  ALGDIV,  BCORR,  GAMLN, 
GAMLN1,  and  GSUMLN.  These  functions  were  written  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  Significant  Digit  Computation  of  the 
Incomplete  Beta  Function  Ratios,  Report  TR  88-365,  Naval  Surface  Warfare  Center, 
Dahlgren,  Virginia,  1988. 

DBETLN(a,  6) 

The  arguments  a  and  b  are  positive  double  precision  numbers.  DBETLN(a,  b)  is  the 
double  precision  value  for  In  B(a,  b). 

Remark.  DBETLN  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Algorithm.  The  algorithm  for  In  B(a,  b)  on  pages  19-21  of  the  reference  is  used.  A(z)  is 
computed  by  the  power  series  corresponding  to  the  Chebyshev  expansion  in  the  SLATEC 
library  given  by  Wayne  Fullerton  (Los  Alamos).  The  power  series  was  obtained  by  A.  H. 
Morris. 

Programming.  DBETLN  employs  the  functions  DLNREL,  DLGDIV,  DBCORR,  DPDEL, 
DGAMLN,  DGMLN1,  and  DGSMLN.  These  functions  were  written  by  A.  H.  Morris.  The 
function  DPMPAR  is  also  used. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  Significant  Digit  Computation  of  the 
Incomplete  Beta  Function  Ratios ,  Report  TR  88-365,  Naval  Surface  Warfare  Center, 
Dahlgren,  Virginia,  1988. 
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INCOMPLETE  GAMMA  RATIO  FUNCTIONS 


For  a  >  0  and  z  >  0  let  P(a,  x )  and  Q(a,  2)  denote  the  functions  defined  by 

P(o'l)=i ml 

$(«.*)  =fj (S)/ 

Then  0  <  P(a,x )  <  1  and  P(a,x )  +  Q(a,z )  =  1.  Also,  P(a,x )  ->  1  and  g(a,i)  ->  0 
for  x  >  0  when  a  — ►  0.  Hence,  we  may  define  P(0,z)  =  1  and  Q(0,z)  =  0  for  z  >  0. 
The  subroutine  GRATIO  is  available  for  computing  P(a,x)  and  Q(a, z),  and  the  auxiliary 
function  RCOMP  is  provided  for  computing  e~xxa/T(a). 

CALL  GRATIO(a,z,P,g,t) 

It  is  assumed  that  o  >  0  and  z  >  0,  where  a  and  z  are  not  both  0.  P  and  Q  are  vari¬ 
ables.  GRATIO  assigns  P  the  value  P(a,z)  and  Q  the  value  Q(a,x).  The  argument  i  may 
be  any  integer.  This  argument  specifies  the  desired  accuracy  of  the  results.  If »'  =  0  then 
the  user  is  requesting  as  much  accuracy  as  possible  (up  to  14  significant  digits).  Otherwise, 
if  *  =  1  then  accuracy  is  requested  to  within  1  unit  of  the  6th  significant  digit,  and  if  *  7^  0, 1 
then  the  accuracy  is  requested  to  within  1  unit  of  the  3rd  significant  digit. 

Error  Return.  P  is  assigned  the  value  2  when  a  or  z  is  negative,  when  a  =  x  =  0,  or 
when  P(a,  z)  and  Q{a,x )  are  indeterminant.  P(a,z)  and  Q(a,x )  are  indeterminant  when 
x  «  a  and  a  is  exceedingly  large.  On  the  GDC  6000-7000  series  computers  this  occurs  when 
| xfa  -  1|  <  10“ 14  and  a  >  6.6E25. 

Programming.  GRATIO  calls  the  functions  ERF,  ERFC1,  REXP,  RLOG,  GAMMA, 
GAM1,  and  SPMPAR.  GAMMA  employs  the  functions  GLOG,  EXPARG,  and  IPMPAR. 
GRATIO  was  written  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

RCOMP(a,z) 

RCOMP(a,  z)  =  e~xxa /T(a)  for  a  >  0  and  z  >  0. 

Algorithm.  See  page  378  of  the  reference. 

Programming.  RCOMP  employs  the  functions  EXPARG,  GAMMA,  GAMl,  GLOG,  and 
RLOG.  These  functions  were  written  by  A.  H.  Morris.  The  functions  SPMPAR  and  IPM¬ 
PAR  are  also  used. 

Reference.  Didonato,  A.  R.  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  their  Inverse,”  ACMTrans.  Math  Software  12  (1986),  pp.  337-393. 
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INVERSE  INCOMPLETE  GAMMA  RATIO  FUNCTION 


For  a  >  0  and  x  >  0  let  P(a,x)  and  Q(a,  x)  denote  the  incomplete  gamma  ratio 
functions  defined  by 


p{a’x)=mJo  e~Ha~ldt 
i  f°° 

q(“’x)=W)L 

Then  0  <  P(a,x)  <  1  and  P(a,i)  +Q(a,x)  =  1.  If  we  are  given  a,p,  and  q  where 
a  >  0,0  <p<  1,  and  p  +  q  =  1,  then  the  subroutine  GAMINV  is  available  for  obtaining 
the  value  x  >  0  for  which  P(a,  x)  =  p  and  Q(a,  x]  —  q. 

CALL  GAMIN V(a,  X,  xo,p,  q,  IND) 

X  is  a  variable.  If  p  =  0  then  X  is  assigned  the  value  0,  and  if  q  =  0  then  X  is  set 
to  the  largest  floating  point  number  available.  Otherwise,  GAMINV  attempts  to  obtain  a 
solution  x  for  P(a,x)  =  p  and  Q(a,x)  =  q  that  is  correct  to  at  least  10  significant  digits.1  If 
the  routine  is  successful  then  the  solution  is  stored  in  X.  The  solution  is  normally  obtained 
by  Schroder  iteration.  The  argument  x0  is  an  optional  initial  approximation  for  x.  If  the 
user  does  not  wish  to  supply  an  initial  approximation  then  set  xq  <  0. 


IND  is  a  variable  that  reports  the  status  of  the  results.  When  GAMINV  terminates, 
IND  has  one  of  the  following  values: 

IND  =  0  The  solution  was  obtained.  Iteration  was  not  used. 

IND  >  1  The  solution  was  obtained.  IND  iterations  were  performed. 

IND  =  -2  (Input  error)  a  <  0. 

IND  =  -3  No  solution  was  obtained.  The  ratio  Q/a  is  too  large. 

IND  =  —4  (Input  error)  p  +  q  ^  1. 

IND  =  -6  20  iterations  were  performed.  The  most  recent  value  obtained  for 
x  is  stored  in  X.  This  cannot  occur  if  xq  <  0. 

IND  =  —7  Iteration  failed.  No  value  is  given  for  x.  This  may  occur  when 
iwO. 

IND  =  -8  A  value  for  x  is  stored  in  X ,  but  the  routine  is  not  certain  of  its 
accuracy.  Iteration  cannot  be  performed  in  this  case.  If  aro  0 
then  this  can  occur  only  when  p  m  0  or  q  «  0.  If  x0  >  0  then  this 
can  occur  when  ami  and  a  is  exceedingly  large  (say  a  >  1020). 


Remark.  If  xq  <  0  then  3  or  fewer  iterations  are  required. 

Programming.  GAMINV  employs  the  routine  GRATIO  and  functions  ERF,  ERFC1, 
REXP,  RLOG,  ALNREL  , GAMMA,  GAM1,  GAMLN,  GAMLN1,  RCOMP,  and  SPMPAR. 

1  If  a  k  digit  floating  point  arithmetic  is  being  used  where  it  <  10,  then  the  routine  attempts  to  obtain  a 
solution  that  is  correct  to  machine  accuracy. 
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GAMMA  uses  the  functions  GLOG,  EXPARG,  and  IPMPAR.  GAMIN V  was  written  by 
A.  H.  Morris 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 
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INCOMPLETE  BETA  FUNCTION 

For  a,b  >  0  and  0  <  x  <  1  the  incomplete  beta  function  is  defined  by 

where  B(a,b )  is  the  beta  function.  Then  we  note  that  0  <  Ix{a,b)  <  1  and 

lim  Ix  [a,  6)  =  1  for  r^O 

a — >0 

lim  Ix{a,b)  =  0  for  x  /  1. 

6 — *0 

These  limits  permit  Ix(a,b)  to  be  defined  to  be  1  when  a  =  0  and  b  ^  0,x  0,  and  for 

Ix(a,b)  to  be  defined  to  be  0  when  6  =  0  and  a  ±  0,x  ^  1.  The  subroutine  BRATIO 
is  available  for  computing  Ix(a,b )  for  arbitrary  a,  6  >  0,  and  the  subroutine  ISUBX  is 
available  for  computing  Zx(a,  6)  for  the  highly  specialized  case  when  a  and  6  are  integers  or 
half-integers.  Also,  the  auxiliary  function  BRCOMP  is  provided  for  computing  xayb/B(a,  b ) 
when  0  <  x  <  1  and  y  =  1  —  x. 

CALL  BRATIO(a,6,x,y,W,Wl,IERR) 

It  is  assumed  that  a  >  0,6  >  0,0  <  x  <  1,  and  y  —  1 -  x.  W,  Wl,  and  IERR  are 
variables.  If  no  input  errors  are  detected  then  IERR  is  set  to  0,  W  is  assigned  the  value 
Ix{a,  6),  and  Wl  is  assigned  the  value  1  —  /x(a,6). 

Error  Return.  When  an  input  error  is  detected,  then  W  and  Wl  are  assigned  the  value  0 
and  IERR  is  set  to  one  of  the  following  values: 

IERR  =1  ifa<0or6<0 
IERR  =  2  if  a  =  6  =  0 
IERR  =  3  ifz<0orx>l 
IERR  =  4  ift/<0ory>l 
IERR  =  5  ifar  +  y^l 
IERR  =  6ifx  =  a  =  0 
IERR  =  7  if  y  =  6  =  0 

Programming.  BRATIO  employs  the  subroutines  BGRAT  and  GRAT1,  and  the  functions 
ALGDIV,  ALNREL,  BASYM,  BCORR,  BETALN,  BFRAC,  BPSER,  BRCOMP,  BRCMP1, 
BUP,  ERF,  ERFC1,  GAMLN,  GAMLN1,  GAM1,  GSUMLN,  ESUM,  EXPARG,  REXP, 
and  RLOG1.  These  subroutines  and  functions  were  written  by  A.  H.  Morris.  The  functions 
SPMPAR  and  IPMPAR  are  also  used. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  Significant  Digit  Computation  of  the 
Incomplete  Beta  Function  Ratios,  Report  TR  88-365,  Naval  Surface  Warfare  Center, 
Dahlgren,  Virginia,  1988. 
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CALL  ISUBX(a,6,x,W,IERR,EPS) 

It  is  assumed  that  a,  b,  and  x  satisfy  the  following  restrictions: 

(1)  a  >  0,6  >  0,  and  x  >  0 

(2)  a  >  1/2, 1/2  <b<  70,  and  x  <  1 

(3)  a  and  b  are  integers  or  half-integers 

EPS  specifies  the  (absolute)  accuracy  that  is  desired.  W  is  a  real  variable  and  IERR  an 
integer  variable.  When  ISUBX  is  called,  if  there  are  no  input  errors  then  W  is  assigned  the 
value  Ix(a,b)  and  IERR  is  assigned  the  value  1. 

Error  Return.  If  an  error  is  detected  then  IERR  is  assigned  one  of  the  following  values: 

IERR  =  2  if  restrictions  (1)  are  violated. 

IERR  =  3  if  restrictions  (2)  are  violated  or  a  is  too  large. 

IERR  =  4  if  restrictions  (3)  are  violated. 

Also  W  is  assigned  the  value  0. 

Remarks.  ISUBX  was  designed  for  a  maximum  precision  EPS  =  10-10 

Programming.  ISUBX  employs  the  functions  ALGDIV,  ALNREL,  BLND,  IPMPAR,  and 
LOGAM.  ISUBX  was  written  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Jarnagin,  M.  P.,  “The  Efficient  Calculation  of  the  Incom¬ 
plete  Beta-function  Ratio  for  Half- Integer  Values  of  the  Parameter  a,b,”  Math  Comp.  21 
(1967),  pp.  652-662. 

BRCOMP  {a,b,x,y) 

BRCOMP(a,  b,  x,  y )  =  xayb / B(a,  b)  for  a,  b  >  0  and  x,  y  >  0  where  x  +  y  =  1. 
Algorithm.  See  pages  19-21  of  the  reference. 

Programming.  BRCOMP  employs  the  functions  ALGDIV,  ALNREL,  BCORR,  BETALN, 
GAM1,  GAMLN,  GAMLN1,  GSUMLN,  and  RLOG1.  These  functions  were  written  by 
A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  H.,  Significant  Digit  Computation  of  the 
Incomplete  Beta  Function  Ratios,  Report  TR  88-365,  Naval  Surface  Warfare  Center, 
Dahlgren,  Virginia,  1988. 
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BESSEL  FUNCTION  J^z) 


If  v  is  complex  then  Jv(z)  is  defined  by 

"  hk,T(,'+k+1) 

for  any  0  in  the  complex  plane  cut  along  the  negative  real  axis.  Jv(z)  is  analytic  in  the 
region  |arg(z)|  <  x,  and  Jw(z)  is  an  entire  function  of  v  for  any  fixed  z.  If  v  is  an  integer 
then  Jv(z)  is  also  defined  at  0  and  is  an  entire  function  of  z.  The  following  subroutines  are 
available  for  computing  J„(z). 

CALLCBSS  U{z,v,w) 

The  arguments  z  and  v  are  complex  numbers  and  w  is  a  complex  variable.  It  is  assumed 
that  [arg(z)j  <  x.  When  CBSSLJ  is  called,  w  is  assigned  the  value  J„(z). 

Precision.  CBSSLJ  is  accurate  to  within  4  •  10“ 13  for  real  0  <  z  <  35  and  0  <  v  <  1. 

Note.  CBSSLJ  employs  the  subroutine  CGAMMA. 

Programmer.  A.  V.  Hershey 


Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginia,  1978. 

CALL  BSSLJ(z,n,w) 

The  argument  z  is  a  complex  number,  n  is  an  integer,  and  w  is  a  complex  variable. 
When  BSSLJ  is  called,  w  is  assigned  the  value  J„(z). 


Precision.  BSSLJ  is  accurate  to  within  5-10  14  for  real  0  <  z  <  35  and  n  =  0, 1 


Programmer.  A.  V.  Hershey 

Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginia,  1978. 

CALL  BESJ(x,a,n,W,Jt) 

The  arguments  x  and  a  are  nonnegative  real  numbers,  n  is  a  positive  integer,  and  W  is 
an  array  of  dimension  n  or  larger.  When  BESJ  is  called  Ja+i_i(x)  is  computed  and  stored 
in  W (i)  for  f  =  1,  . . . ,  n. 
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The  argument  A:  is  an  integer  variable  that  is  set  by  the  routine.  If  all  Ja+,_i(x)  are 
computed  then  k  is  set  to  0.  Otherwise,  k  is  assigned  one  of  the  following  values: 

k  =  —  1  The  argument  x  is  negative. 
k  =  —  2  The  argument  a  is  negative. 
k  =  —  3  The  requirement  n  >  1  is  violated. 

k  >  0  The  last  k  components  of  W  have  been  set  to  0  because  of  under¬ 

flow. 

Precision.  For  0  <  x  <  35  and  0  <  a  <  1,  BESJ  is  accurate  to  within  8  •  10-13. 

Programming.  BESJ  calls  the  subroutines  ASJY  and  JAIRY,  and  the  functions  GAMLN, 
SPMPAR,  and  IPMPAR.  The  subroutines  were  written  by  Donald  E.  Amos,  Sharon  L. 
Daniel,  and  M.  Katherine  Weston  (Sandia  Laboratories). 

References. 

(1)  Amos,  D.E.,  Daniel,  S.  L.,  and  Weston,  M.  K.,  CDC  6600  Subroutines  for  Bessel 

Functions  Ju(x),x  >  0,i/  >  0  and  Airy  Functions  oo  <  x  <  oo.  Report 

SAND  75-0147,  Sandia  Laboratories,  Albuquerque,  New  Mexico,  1975. 

(2)  _  ,  “CDC  6600  Subroutines  IBESS  and  JBESS  for  Bessel  Functions  Iv(x) 

and  Jl/(x),x  >  0,  v  >  0,”  ACM  Trans.  Math  Software  3  (1977),  pp.  76-92. 
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BESSEL  FUNCTION  Y„(z) 


If  v  is  any  complex  number  not  an  integer,  then  Yy(z)  can  be  defined  by 

^  f_x  _  Jv{z)  cos  z/jt  -  J_„(z) 

*v\z)  —  : 

sin  i/jt 

for  any  z  yt  0  in  the  complex  plane  cut  along  the  negative  real  axis.  For  any  integer  n  we 
can  also  define  Yn(z)  =  lim  Yy(z).  Then  for  any  complex  v,  Yv  (z)  is  analytic  in  the  region 

v — 

|arg(z)|  <  jt.  Also,  Yv{z)  is  an  entire  function  of  v  for  any  fixed  z.  The  following  subroutine 
is  available  for  computing  Yy  (z)  when  v  is  an  integer. 

CALL  BSSLY(z,n,  tu) 

The  argument  z  is  a  complex  number,  n  is  an  integer,  and  it;  is  a  complex  variable.  It 
is  assumed  that  |arg(z)|  <  t.  When  BSSLY  is  called,  u/  is  assigned  the  value  Yn(z). 

Precision.  If  .005  <  x  <  .785  then  Yo(z)  and  Yi{x)  are  accurate  to  within  3  units  of  the 
14th  significant  digit.  Otherwise,  if  x  >  .785  then  Yo(z)  and  Yi(z)  are  accurate  to  within 
4  ■  10-14. 

Programmer.  A.  V.  Hershey 

Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginia,  1978. 
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MODIFIED  BESSEL  FUNCTION  l„(a) 

If  v  is  complex  then  /„(z)  is  defined  by 


CO 

=  E 


k=0 


(z/2y+2k 

jfcir(v  +  fc  +  i) 


for  any  z  ^  0  in  the  complex  plane  cut  along  the  negative  real  axis.  Iv(z)  is  analytic  in  the 
region  |arg(z)|  <  7r,  and  Iv{z)  is  an  entire  function  of  v  for  any  fixed  z.  If  v  is  an  integer 
then  Iu(z)  is  also  defined  at  0  and  is  an  entire  function  of  z.  The  following  subroutines  are 
available  for  computing  Iv  ( z ) . 

CALL  BSSLI(MO, z, n,  w) 

MO  is  am  integer,  z  a  complex  number,  n  an  integer,  and  w  a  complex  variable.  If  MO 
0  then  it  is  assumed  that  |arg(z)|  <  jr.  When  BSSLI  is  called,  w  is  assigned  the  value 
J„(z)  if  MO  =  0  and  the  value  e~*In(z)  if  MO  yt  0. 

Precision.  BSSLI  is  accurate  to  within  5  units  of  the  13th  significant  digit  for  real  0  <  z  <  35 
and  n  =  0, 1,  . . .  ,40. 


Programmer.  Allen  V.  Hershey 

Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginia,  1978. 

CALL  BESI(s, a, MO,  n,  W, k) 

MO  may  be  1  or  2.  The  arguments  x  and  a  are  nonnegative  real  numbers,  n  is  a 
positive  integer,  and  W  is  an  array  of  dimension  n  or  larger.  When  BESI  is  called,  if  MO 
=  1  then  Ia+i-i(x)  is  computed  and  stored  in  W (»)  for  *  =  1, ... ,  n.  Otherwise,  if  MO  =  2 
then  e-x/a+t_1(x)  is  computed  and  stored  in  W(»‘) 

The  argument  &  is  an  integer  variable  that  is  set  by  the  routine.  If  all  f0+,-_1(®)  or 
e~xIa+i-i{x)  are  computed  then  k  is  set  to  0.  Otherwise,  k  is  assigned  one  of  the  following 
values: 

k  =  —  1  The  argument  x  is  negative, 
k  =  -2  The  argument  a  is  negative, 
k  =  —  3  The  requirement  n  >  1  is  violated, 
k  =  —4  MO  is  not  1  or  2. 

k  =  -5  The  argument  x  is  too  large  for  MO  =  1. 

k  >  0  The  last  k  components  of  W  have  been  set  to  0  because  of  underflow. 

Precision.  For  0  <  *  <  35  and  0  <  a  <  1,  or  0  <  x  <  35  and  a  =  1,2  ... ,40,  Ia(x )  is 
accurate  to  within  2  units  of  the  12th  significant  digit. 
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Programming.  BESI  calls  the  subroutine  ASIK  and  the  functions  GAMLN,  SPMPAR, 
and  IPMPAR.  BESI  and  ASIK  were  written  by  D.  E.  Amos  and  S.  L.  Daniel  (Sandia 
Laboratories) . 

References. 

(1)  Amos,  D.  E.  and  Daniel,  S.  L.,  A  CDC  6600  Subroutine  for  Bessel  Functions 
I„(x),v  >  0,x  >  0.  Report  SAND  75-0152,  Sandia  Laboratories,  Albuquerque,  New 
Mexico,  1975. 

(2)  Amos,  D.  E.,  Daniel,  S'.  L.,  and  Weston,  M.  K.,  “CDC  6600  Subroutines  IBESS  and 

JBESS  for  Bessel  Functions  and  Jv (x) ,  x  >  0,  v  >  0,”  ACM  Trans.  Math 

Software^  (1977),  pp.  76-92. 
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MODIFIED  BESSEL  FUNCTION  K„(z) 


If  v  is  any  complex  number  not  an  integer,  then  K„{z)  is  defined  by 

Kv{z)  =  -L± 

2  sm  vk 

for  any  z  ^  0  in  the  conplex  plane  cut  along  the  negative  real  axis.  For  any  integer  n 
we  can  also  define  Kn(z)  —  lim  K„(z).  Then  for  any  complex  v,K„(z)  is  analytic  in  the 

region  |arg(z)|  <  tt.  Also,  Kv{z)  is  an  entire  function  of  v  for  any  fixed  z.  The  following 
subroutines  are  available  for  computing  Kv(z). 

CALL  CBSSLK(z,  r,  w) 

The  argument  z  is  a  complex  number,  r  is  a  real  number,  and  w  is  a  complex  variable. 
It  is  assumed  that  |arg(z)|  <  jr.  When  CBSSLK  is  called,  w  is  assigned  the  value  Kr(z). 

Programmer.  Allen  V.  Hershey 

Reference.  Hershey,  A.  V.,  Approximations  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 

CALL  BSSLK(MO,'z,  n,  tt;) 

MO  is  an  integer,  z  a  complex  number,  n  an  integer,  and  w  a  complex  variable.  It  is 
assumed  that  |arg(z)|  <  tt.  When  BSSLK  is  called,  w  is  assigned  the  value  Kn{z)  if  MO 
=  0  and  the  value  ezKn(z)  if  MO  /  0. 

Precision.  BSSLK  is  accurate  to  within  6  units  of  the  14th  significant  digit  for  real  z  and 
n  =  0, 1. 

Programmer.  Allen  V.  Hershey 

Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginina,  1978. 
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AIRY  FUNCTIONS 


For  any  series  w  —  E  anzn  satisfying  the  differential  equation  tv"  =  zw,  it  follows 

n=0 

that  w  =  aof(z)  +  a\g{z )  where 

f{z)  =1+  E 

n>l 

g{z)  =1  +  E 

n>l 

In  particular,  the  Airy  functions  Ai(z)  and  Bi(z)  are  independent  solutions  of  tv"  =  zw 
where 

Ai(z )  =  Ci/(z)  -  c2g(z) 

Bi(z)  =.y/Z  [ci/(z)  +  c2g(z )] 

for  ci  =  3-2/s/r(2/3)  and  c2  =  3-1/s/r(l/3).  Ai{z)  and  Bi{z)  are  entire  functions. 

The  subroutines  CAI  and  CBI  are  available  for  computing  Ai(z)  and  Bt(z)  when  z  is 
complex,  and  the  functions  AI,  AIE,  BI,  and  BIE  are  available  for  computing  Ai{z)  and 
Bi{z)  when  z  is  real.  CAI  and.  CBI  also  provide  the  dervatives  At'(z)  and  Bi'(z)  of  Ai(z) 
and  Bi{z). 

CALL  CAI(IND,z, w,w' ,IERR) 

IND  is  an  integer,  z  a  complex  number,  and  u;  and  tv'  complex  variables.  When  CAI 
is  called,  w  is  assigned  the  value  Ai(z)  and  w1  the  value  Ai'{z)  when  IND  =  0.  Otherwise, 
if  IND  ^  0  then  w  =  esAi(z)  and  w'  =  etAi'{z )  where  f  =  | zs!2. 

IERR  is  a  variable  that  is  set  by  the  routine.  When  CAI  terminates,  IERR  has  one  of 
the  following  values: 

IERR  =  0  The  desired  values  were  obtained. 

IERR  ==  1  z  is  too  large  for  the  desired  values  to  be  computed.  In  this  case 
xv  and  w'  sire  assigned  the  value  0. 


2-5— (3w— 1)  3n+I 
(3n+l)l  z 


Precision.  For  IND  yt  0  the  real  and  imaginary  parts  of  w  and  tv'  are  accurate  to  within  2 
units  of  the  12th  significant  digit  except  near  points  where  they  vanish. 

Programming.  CAI  employs  the  subroutines  AIRM,  All,  AIA,  JA,  JMC,  BJM,  KA,  KML, 
IMC,  and  BIM.  These  routines  were  written  by  Andrew  H.  van  Tuyl  (NSWC)  and  modified 
by  A.  H.  Morris.  The  subroutines  CAPO  and  CREC,  and  functions  CPABS,  EXPARG, 
IPMPAR,  and  SPMPAR  sure  also  used. 

CALL  CBI(IND,z,  w,  «/,IERR) 
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IND  is  an  integer,  z  a  complex  number,  and  u;  and  w'  complex  variables.  When  CBI 
is  called,  w  is  assigned  the  value  Bt(z)  and  w1  the  value  Bi'(z)  when  IND  =  0.  Otherwise, 
if  IND  #  0  then 


w  = 


U)  = 


where  f  =  §  z3/2. 


e  *  Bi(z) 
e!Bt(z) 

e~s  Bt'(z) 
es  Bt'(z) 


if  |arg(z)[  <  jt/3 
otherwise 

if  |arg(z)|  <  7t/3 
otherwise 


IERR  is  a  variable  that  is  set  by  the  routine.  When  CBI  terminates,  IERR  has  one  of 
the  following  values: 

IERR  =  0  The  desired  values  were  obtained. 

IERR  =  1  z  is  too  large  for  the  desired  values  to  be  computed.  In  this  case 
w  and  w'  are  assigned  the  value  0. 


Precision.  For  IND  ^  0  the  real  and  imaginary  parts  of  tu  and  w'  are  accurate  to  within  2 
units  of  the  12th  significant  digit  except  near  points  where  they  vanish. 

Programming.  CBI  employs  the  subroutines  AIRM,  BII,  BIA,  LA,  IMC,  BIM,  JA,  JMC, 
and  BJM.  These  routines  were  written  by  Andrew  H.  van  Tuyl  (NSWC)  and  modified  by 
A.  H.  Morris.  The  subroutine  CREC  and  functions  CPABS,  EXPARG,  IPMPAR,  and 
SPMPAR  are  also  used. 

Al(x) 

AI(x)  =  Ai(x)  for  real  x. 

Algorithm.  Rational  minimax  approximations  are  used.  If  x  <  —1  then  R  and  0  are 
computed  where  Ai(x)  =  R  sin(?r/4  +  9). 

Precision.  For  x  >  —  1,  AI(x)  is  accurate  to  within  2  units  of  the  12th  significant  digit  when 
AI(x)  ^0. 

Programming.  AI  calls  the  subroutine  AIMP  and  function  EXPARG.  These  subprograms 
were  written  by  A.  H.  Morris.  The  function  IPMPAR  is  also  used. 

AIE(x) 

If  x  >  0  then  AIE(x)  =  ef  Ar(x)  where  f  =  §x3/2.  Otherwise,  if  x  <  0  then  AIE(x)  = 
At(x). 

Algorithm.  Rational  minimax  approximations  cire  used.  If  x  <  —1  then  R  and  9  are 
computed  where  Ar(x)  =  f?  sin  (jt/4 +  0). 

Precision.  For  x  >  —  1,  AIE(x)  is  accurate  to  within  2  units  of  the  14th  significant  digit. 
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Programming.  AIE  calls  the  subroutine  AIMP.  AIE  and  AIMP  were  written  by  A.  H. 
Morris. 

Bl(x) 

BI(x)  =  Bi(x)  for  real  x.  If  x  is  a  positive  value  for  which  Bi(x)  is  too  large  to  be 
computed,  then  BI(x)  is  assigned  the  value  0. 

Algorithm.  Rational  minimax  approximations  are  used.  If  x  <  -1  then  R  and  6  are 
computed  where  Bi(x)  =  R  cos(jt/4  +  9). 

Precision.  For  x  >  —  1,  BI(x)  is  accurate  to  within  2  units  of  the  12th  significant  digit  when 
BI(x)  56  0. 

Programming.  BI  calls  the  subroutine  AIMP  and  function  EXPARG.  These  subprograms 
were  written  by  A.  H.  Morris.  The  function  IPMPAR  is  also  used. 

BIE(a) 

If  x  >  0  then  BIE(z)  =  e~sBt(x)  where  f  =  |z3/2 .  Otherwise,  if  x  <  0  then  BIE(z)  = 
Bi(x). 

Algorithm.  Rational  minimax  approximations  are  used.  If  x  <  -1  then  R  and  9  are 
computed  where  Bi( x)  =  R  cos(jt/4  +  9). 

Precision.  For  x  >  —1,  BIE(z)  is  accurate  to  within  2  units  of  the  14th  significant  digit. 

Programming.  BIE  calls  the  subroutine  AIMP.  BIE  and  AIMP  were  written  by  A.  H. 
Morris. 
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COMPLETE  COMPLEX  ELLIPTIC  INTEGRALS  OF  THE 
FIRST  AND  SECOND  KINDS 


If  k  is  complex  then  the  complete  elliptic  integrals  of  the  first  and  second  kinds  can  be 
defined  by 


r*'1 

K(k)  =  I  (1  —  k 2  sin2*)-1/3  dt 
Jo 
f *72 

E(k)  —  I  (1  —  k3  sin2*)1/3  dt 
Jo 

for  |arg(l  —  fc2)|  <  x.  K(k)  and  E(k)  can  be  extended  to  —x  <  arg(l  — jfe3)  <  x.  For  |A:|  <  1 

m  = 


(i) 


n>  0 


E(k)  =  --Tcn-!^- 

v  '  2  •“  2n  —  1 


n>0 


where  cn  = 


(2»)l 

4”(n!)5 


n  2 


.  Also,  if  £2  =  1  —  k2  where  |£|  <  1  and  —  x  <  arg(£2)  <  x,  then 


(2) 


^  -  g  t  *  S-sSf- 


The  function  CK  is  available  for  computing  K(k),  and  the  subroutine  CKE  for  computing 
K{k)  and  E{k). 

CK(fc,£) 

CK(fc,  £)  =  K (A:)  for  any  complex  k  and  £  where  A:2 + £2  =  1  and  £  ^  0.  CK  is  a  complex 
valued  function  which  must  be  declared  in  the  calling  program  to  be  of  type  COMPLEX. 


Error  Return.  CK(A:,£)  =  0  if  £  =  0  or  A:2  +  £2  ^  1. 

Remarks. 

(1)  CK(A;,£)  may  underflow,  yielding  the  value  D,  when  |Ar|  is  sufficiently  large. 

(2)  CK  and  the  subroutine  CKE  employ  the  same  algorithm  for  K(k). 
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Precision.  If  A:  is  real  and  |A:|  <  1  then  the  relative  error  of  CK  is  less  than  10-13.  Also,  if 
k  is  purely  imaginary  then  the  relative  error  is  less  than  10~13.  K(k)  is  real- valued  for  only 
these  values  of  k.  Otherwise,  let  e*  —  10~12  if  |A:|  <  0.8,  e*  =  2- 10~13  if  0.8  <  |fc|  <  2,  and 
sfe  =  10“ 13  if  |fc|  >  2.  Then  the  relative  errors  of  the  real  and  imaginary  parts  of  CK  are 
less  than  e*  except  when  underflow  occurs,  |fc|  <  1  and  |arg(±A:)|  <  10”287,  or  |A:|  <  1015 
and  |jt/2  —  arg(±&)|  <  10-280.  In  the  latter  two  cases  the  relative  error  of  the  real  part  of 
CK  is  less  than  £fc,  but  all  relative  accuracy  for  the  imaginary  part  may  be  lost. 

Programming.  CK  calls  the  subroutine  KL  and  functions  ALNREL,  CFLECT,  KM,  and 
SPMPAR.  CK,  KL,  and  KM  were  written  by  Andrew  H.  van  Tuyl  (NSWC)  and  modified 
by  A.  H.  Morris. 

CALL  CKE(Jfe,  £,  K,  E, IERR) 

The  arguments  k  and  £  are  complex  numbers  where  k2  +  £2  =  1  and  £  ^  0,  K  and  E 
are  complex  variables,  and  IERR  an  integer  variable.  When  CKE  is  called,  if  no  errors  are 
detected  then  IERR  is  set  to  0,  K  is  assigned  the  value  K(k),  and  E  is  assigned  the  value 

m- 

Error  Return.  IERR  =  1  if  £  =  0  and  IERR  =  2  if  k2  +  i2  1.  In  these  cases,  K  and  E 
are  not  defined. 

Algorithm.  For  k  =  0  or  —  n/2  <  arg(fc)  <  sr/2,  formulae  (2)  are  used  if  |£|  <  .55,  (1)  are 
used  if  |£|  >  .55  and  |fc|  <  .55,  and  approximations  of  the  form 

n=l  n 

(3) 

=  l  +  ^tan-‘Y 

n=l  L 

are  used  if  |£]  >  .55  and  .55  <  |A:|  <  1.  (3)  are  obtained  from  integral  representations  for 
K(k)  and  E(k)  by  numerical  quadrature.  If  |£|  >  .55,  |A:|  >  1,  and  |A:|  <  |£|  then 

K{k)  =  £i  K(Jfci)  ki  =  ±ikfl 

(4) 

E{k)  =  E(ki)/ti  L\  —  \/t 

are  applied  where  the  sign  in  ki  is  selected  so  that  —  ir/2  <  arg(fci)  <  jt/2.  Otherwise,  if 
|£|  >  .55,  |A:|  >  1,  and  \k\  >  |£|  let  ki  =  1  jk  and  £i  =  ±.itjk  where  the  sign  is  selected  so 
that  —  n/2  <  arg(£x)  <  n/2.  Then 

K{k)  =  ki[K{k1)  +  iaK{l1)] 

(5) 

E(k)  =  —[Eikt)  -  t\  K(ki)  -  is  (E(£ i)  -  k2  K(£r))] 

*  l 
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are  applied  where  s  =  1  if  Im(A:)  >  0  and  s  =  —  1  if  Im(fe)  <  0.  If  arg(ifc)  >  it  f  2  or 
arg(fc)  <  —it 1 2,  then  K(k)  =  K(—k )  and  E(k )  =  E{—k )  are  applied. 

Precision.  If  A:  is  real  and  |fc|  <  1,  or  k  is  purely  imaginary,  then  the  relative  error  of  E  is 
less  than  10~13.  E(k)  is  real-valued  for  only  these  values  of  k.  Otherwise,  let  e*  =  10~12  if 
|A:[  <  2  and  e*  =  10~13  if  |A:|  >  2.  Then  the  relative  errors  of  the  real  and  imaginary  parts 
of  E  are  less  than  ek  except  when  underflow  occurs,  |fc|  <  1  and  |arg(±fc)|  <  10-280,  or 
[Ac|  <  1015  and  |tt/2  —  arg(±fc)|  <  10“28°.  In  the  latter  two  cases  the  relative  error  of  the 
real  part  of  E  is  less  than  e*,,  but  all  relative  accuracy  for  the  imaginary  part  may  be  lost. 

Programming.  CKE  calls  the  subroutines  EKL  and  EKM,  and  the  functions  ALNREL, 
ATN,  CFLECT,  and  SPMPAR.  CKE  was  written  by  Andrew  H.  van  Tuyl  (NSWC). 
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REAL  ELLIPTIC  INTEGRALS  OF  THE  FIRST  AND  SECOND  KINDS 

If  0  <  <£  <  jt/2,  then  the  elliptic  integrals  of  the  first  and  second  kinds  are  defined  by 

F(<f>,  k)  =  f  (1  -  k2  sin2f)-1/2  dt 

Jo 

E{4>, k)  —  I f  (1  -  k2  sin2*)1/2  dt 
Jo 

for  any  real  k  where  k2  <  1  and  I  -  A:2  sin2^  ^  0.  Alternatively,  we  may  consider 

1  C°° 

RF(a,b,c)  =  -  j  [(* +  a)(£ +  &)(£  + c)]~1/2di 
where  a,  b,  c  are  nonnegative  and  at  most  one  of  them  is  0,  and 

RD(a,  6,c)  =  |  J~(t  +  +  b)~^(t  +  c)~3/2  dt 

where  a  and  b  are  nonnegative  such  that  a  +  b  >  0,  and  c  is  positive.  If  a  <  b  <  c  and  a  <  c 
then 


RF(a,b,c) 


Ro{a,b,  c) 


c-V* 


F{<t>,k) 


3c~3/2 
k 2  sin3^ 


F(<fi,k)-E(t,k) 


where  cos2<£  =  a/c  and  k2  =  (c  -  b)/(c  -a).  If  <f>  =  jt/2  then  the  integrals  F{(j>,k )  and 
E{<j>,k )  are  said  to  be  complete.  Otherwise,  if  <f>  <  tt/2  then  the  integrals  are  said  to  be 
incomplete.  The  subroutines  ELLPI,  RFVAL,  RDVAL,  DELLPI,  DRFVAL,  and  DRDVAL 
are  available  for  computing  F(<f>,  k),  E(<j>,  k),  RF(a,  b,  c)  and  #0(0, 6, c).  DELLPI,  DRFVAL, 
and  DRDVAL  are  double  precision  routines. 

CALL  ELLPI(<£,  t/>,  k,  i,  F,  E,  IERR) 

The  arguments  <f>,\p,k,l  are  real  numbers  which  satisfy  <f>  >  0,ip  >  0,<f>  +  xp  =  v/2,  and 
k2  + 12  =  1.  Also,  if  ip  =  0  then  it  is  assumed  that  i  ^  0.  F,E,  and  IERR  are  variables. 
When  ELLPI  is  called,  if  no  input  errors  are  detected  then  IERR  is  set  to  0,  F  is  assigned 
the  value  F(<f>,k),  and  E  is  assigned  the  value  E(<f>,k). 


Error  Return.  If  an  input  error  is  detected  then  IERR  is  set  as  follows: 

IERR  =1  <f>  <  0  or  ip  <  0 
IERR  =  2  |&[  >  1  or  |£|  >  1 
IERR  =  3^  =  0  and  t  =  0 
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Precision.  ELLPI  is  accurate  to  within  4  units  of  the  14th  significant  digit. 

Programming.  ELLPI  calls  the  functions  ALNREL  and  CPABS.  ELLPI  was  written  by 
Allen  V.  Hershey  and  modified  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Hershey,  A.  V.,  “New  Formulas  for  Computing  Incomplete 
Elliptic  Integrals  of  the  First  and  Second  Kind,”  JACAf  6  (1959),  pp.  515-526. 

CALL  RFVAL(a,  b,  c,  w,  IERR) 

The  arguments  a,  b,  c  are  nonnegative  real  numbers,  only  one  of  which  can  be  0.  IERR 
and  w  are  variables.  When  RFVAL  is  called,  if  no  input  errors  are  detected  then  IERR  is 
set  to  0  and  w  is  assigned  the  value  Rp{a,  b,  c). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 

IERR  =  1  Either  o,  6,  or  c  is  negative. 

IERR  =  2  Either  a  +  b,  a  +  c,  or  b  +  c  is  too  small. 

IERR  =  3  Either  a,  b,  or  c  is  too  large. 

Precision.  RFVAL  is  accurate  to  within  4  units  of  the  14th  significant  digit. 

Programming.  RFVAL  was  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
University),  and  modified  by  A.  H.  Morris.  The  function  SPMPAR  is  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _  and  Notis,  E.  M.,  “Algorithm  577.  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  RDVAL(a,6,c,  tu,IERR) 

The  arguments  a  and  b  are  nonnegative  real  numbers  where  a  +  b  >  0,  and  c  is  a 
positive  real  number.  IERR  and  w  are  variables.  When  RDVAL  is  called,  if  no  input  errors 
are  detected  then  IERR  is  set  to  0  and  w  is  assigned  the  value  Ro{a,b,c). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 

IERR  =  1  Either  a,  b,  or  c  is  negative. 

IERR  =  2  Either  a  +  b  or  c  is  too  small. 

IERR  =  3  Either  a,b,  or  c  is  too  large. 

Precison.  RDVAL  is  accurate  to  within  4  units  of  the  14th  significant  digit. 

Programming.  RDVAL  was  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
University),  and  modified  by  A.  H.  Morris.  The  function  SPMPAR  is  used. 
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References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  DELLPI(0,^M,E,£,IERR) 

The  arguments  <f>,  rfr,  k,£  are  double  precision  numbers  where  <f>  >  0,  rp  >  0,  =  jt/2, 

and  k2  +  £2  =  1.  Also,  if  =  0  then  it  is  assumed  that  1^0.  F  and  E  are  double  precision 
variables,  and  IERR  is  an  integer  variable.  When  DELLPI  is  called,  if  no  input  errors  are 
detected  then  IERR  is  set  to  0,  F  is  assigned  the  double  precision  value  for  F(<f>,  £),  and  E 
is  assigned  the  double  precision  value  for  E{<j> ,  k). 

Error  Return.  If  an  input  error  is  detected  then  IERR  is  set  as  follows: 

IERR  =  1  ^  <  0  or  <  0 
IERR  =2  |fc|  >  1  or  |£|  >  1 
IERR  =3^  =  0  and  £  =  0 

Precision.  DELLPI  is  accurate  to  within  5  units  of  the  28th  significant  digit. 

Programming.  DELLPI  employs  the  functions  DCPABS,  DLNREL,  and  DPMPAR. 
DELLPI  was  written  by  Allen  V.  Hershey  and  modified  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Hershey,  A.  V.,“New  Formulas  for  Computing  Incomplete 
Elliptic  Integrals  of  the  First  and  Second  Kind,”  3 ACM  6  (1959),  pp.  515-526. 

CALL  DRFVAL(a,  b,  c,  w,  IERR) 

The  arguments  a,  b,  c  are  nonnegative  double  precision  numbers,  only  one  of  which  can 
be  0.  IERR  is  an  integer  variable  and  w  a  double  precision  variable.  When  DRFVAL  is 
called,  if  no  input  errors  are  detected  then  IERR  is  set  to  0  and  ty  is  assigned  the  double 
precision  value  for  Ejp(a,b,c). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 
IERR  =  1  Either  a,  b,  or  c  is  negative. 

IERR  =  2  Either  a  +  b,  a  +  c,  or  b  +  c  is  too  small. 

IERR  =  3  Either  a,  b,  or  c  is  too  large. 

Programming.  DRFVAL  was  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
University),  and  modified  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 
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(2)  _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  DRDVAL(a,  b,c,w,  IERR) 

The  arguments  a  and  b  are  nonnegative  double  precision  numbers  where  a  +  b  >  0, 
and  c  is  a  positive  double  precision  number.  IERR  is  an  integer  variable  and  w  a  double 
precision  variable.  When  DRDVAL  is  called,  if  no  input  errors  are  detected  then  IERR  is 
set  to  0  and  w  is  assigned  the  double  precision  value  for  Ru(a,b,c). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 

IERR  =  1  Either  a,  b,  or  c  is  negative. 

IERR  =  2  Either  a  +  b  or  c  is  too  small. 

IERR  =  3  Either  a,  b,  or  c  is  too  large. 

Programming.  DRDVAL  was  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
University),  and  modified  by  A.  H.  Morris.  The  function  DPMPAR  is  used. , 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 
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REAL  ELLIPTIC  INTEGRALS  OF  THE  THIRD  KIND 

For  any  0  <  <f>  <  tt/2  the  elliptic  integral  IT(^,  n,fc)  is  defined  by 
n(<£,n,  k)  =  f  (1  -  nsin20)-1(l  -  A:2 sin2  9)~%d0 

Jo 

where  n  is  any  real  number  such  that  1  -  nsin2  <f>  ■£  0,  and  it  any  real  number  such  that 
ic 2  <  1  and  1  -  k2  sin2  0.  Alternatively,  for  any  0  we  may  consider 


Rj(a, 


+  r)  1  [(t  +  a)(t  +  b)(t  +  c)]  3  dt 


where  a,  b,  c  are  nonnegative  and  at  most  one  of  them  isO.  If  a  <  6  <  c  and  a  <  c  then 

_  _  3 

Rj(a,b,c,r)  =  — ■  3  [II(&n,fc)  -  F(<f>,k)] 
n  sin  <p 

where  k)  is  the  elliptic  integral  of  the  first  kind,  cos2  <f>  =  a/c,k2  =  (c -b)/(c- a),  and 
n  =  (c  -  r)/(c  -  a).  If  <f>  =  n/2  then  the  elliptic  integral  II(^,n,jt)  is  said  to  be  complete. 
Otherwise,  if  <f>  <  n /2  then  the  integral  is  said  to  be  incomplete..  The  subroutines  EPI, 
RJVAL,  DEPI,  and  DRJVAL  are  available  for  computing  II(<£,  n,  k)  and  Rj (a,  b,  c,  r).  DEPI 
and  DRJVAL  are  double  precision  routines. 

CALL  EPI^.^fc2, £2,n,m, tn,IERR) 

The  arguments  <f>,ip,k2  ,£2  ,n,m  are  real  numbers  where  <f>  >  0,ip  >  0,<f>+  ip  =  jt/2, 
k2  +  £2  =  1,  |n|  <  1,  and  n  +  m  =  1.  Also,  if  rp  =  0  then  it  is  assumed  that  £2  ^  0  and 
IERR  and  w  are  variables.  When  EPI  is  called,  if  no  input  errors  are  detected  then 
IERR  is  set  to  0  and  w  is  assigned  the  value  n(^,  n,  Jfc). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 
IERR  =  1  Either  <j>  or  t/>  is  negative,  or  tj>  +  if)  ^  jt/2. 

IERR  =  2  Either  jn|  >  1  or  n  +  m  ^  1. 

IERR  =  3  Either  k2  or  £2  is  negative,  or  k2  +  £2  ^  1. 

IERR  =  4  Either  t/>  and  m  are  too  close  to  0,  or  and  £2  are  too  close  to  0. 


Precision.  EPI  is  accurate  to  within  4  units  of  the  14tfc  significant  digit. 

Programming.  EPI  employs  the  subroutines  RFVAL,  RJVAL,  RCVAL1  and  function  SPM- 
PAR.  EPI  was  written  by  A.H.  Morris. 

CALL  RJ VAL(a,  b,  c,  r,  u/,IERR) 

The  arguments  a,b,c  are  nonnegative  real  numbers,  only  one  of  which  can  be  0,  and  r 
is  a  positive  real  number.  IERR  and  w  are  variables.  When  RJVAL  is  called,  if  no  input 
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errors  are  detected  then  IERR  is  set  to  0  and  w  is  assigned  the  value  Rj(a,  b,  c,  r). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 
IERR  =  1  Either  a,  b,  c,  or  r  is  negative. 

IERR  =  2  Either  a  +  b,a  +  c,b  +  c,  or  r  is  too  small. 

IERR  =  3  Either  o,  b ,  c,  or  r  is  too  large. 

Precision.  RJVAL  is  accurate  to  within  4  units  of  the  14tfc  significant  digit. 

Programming.  RJVAL  cedis  the  subroutine  RCVAL1.  These  subroutines  were  written  by 
B.C.  Carlson  and  Elaine  M.  Notis  (Iowa  State  University),  and  modified  by  A.H.  Morris. 
The  function  SPMPAR  is  also  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication.”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577, Algorithms  for  Incomplete  Elliptic 

Integrals.”  ACM  Trans.  Math  Software  7  (1981), pp.398-403. 

CALL  DEPI(^,  ip,  k2 ,t2 ,  n,  m,  w,IERR) 

The  arguments  <p,  ip,  k2 are  double  precision  numbers  where  <p  >  0,  ip  >  0, <p  + 
ip  =  tt/2,  k2  +  £2  —  1,  |n|  <  1,  and.n+  m  =  1.  Also,  if  ip  —  0  then  it  is  assumed  that  Z2  ^  0 
and  m  0.  IERR  is  an  integer  variable  and  w  a  double  precision  variable.  When  DEPI  is 
called,  if  no  input  errors  are  detected  then  IERR  is  set  to  0  and  w  is  assigned  the  double 
precision  value  for  IT(0,  n,  k). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 

IERR  =  1  Either  <p  or  ip  is  negative,  or  <p  +  ip  jr/2. 

IERR  =  2  Either  |n|  >  1  or  n  +  m  /  1. 

IERR  =  3  Either  k 2  or  £2  is  negative,  or  k2  +  £2  ^  1. 

IERR  =  4  Either  ip  and  m  are  too  close  to  0,  or  ip  and  £2  are  too  close  to  0. 

Programming.  DEPI  employs  the  subroutines  DRFVAL,  DRJVAL,  DRCVL1  and  function 
DPMPAR.  DEPI  was  written  by  A.H.  Morris. 

CALL  DRJVAL(a,  6,c,  r,tu,IERR) 

The  arguments  a,  b,  c  are  nonnegative  double  precision  numbers,  only  one  of  which  can 
be  0,  and  r  is  a  positive  double  precision  number.  IERR  is  an  integer  variable  and  w  a 
double  precision  variable.  When  DRJVAL  is  called,  if  no  input  errors  are  detected  then 
IERR  is  set  to  0  and  w  is  assigned  the  double  precision  value  for  Rj(a,b,c,r). 

Error  Return.  If  an  input  error  is  detected  then  IERR  has  one  of  the  following  values: 
IERR  =  1  Either  a,  b,  c,  or  r  is  negative. 

IERR  =  2  Either  a  +  b,  a  +  c,  b  +  c,  or  r  is  too  small. 
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IERR  =  3  Either  a,  b,  c,  or  r  is  too  large. 


Programming.  DRJVAL  calls  the  subroutine  DRCVL1.  These  subroutines  were  written  by 
B.C.  Carlson  and  Elaine  M.  Notis  (Iowa  State  University),  and  modified  by  A.H.  Morris. 
The  function  DPMPAR  is  also  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication.”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  - and  Notis,  E.  M.,  “Algorithm  577, Algorithms  for  Incomplete  Elliptic 

Integrals.”  ACM  Trans.  Math  Software  7  (1981),pp.398^403. 
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JACOBIAN  ELLIPTIC  FUNCTIONS 


For  any  complex  number  k  ^  0,  ±1  the  elliptic  function  sn(z,  Jb)  may  be  defined  as  the 
meromorphic  function  w(z )  that  satisfies 

(1)  (£)’  = 

tu(0)  =  0,  u/(0)  =  1. 

If  A:  =  0  then  sn(z,  0)  =  sin  z  satisfies  (1),  and  if  k  —  ±1  then  sn(z,  k )  =  tanh  z  satisfies  (1). 
Alternatively,  sn(z,  k)  =  sin  <j>  where  <f>{z)  satisfies 

(2)  (S)  =  1 

^(0)  =  0,  *'(0)  =  1. 

The  elliptic  functions  cn{z,  k )  and  dn(z,  k )  may  be  defined  by 

cn[z,k)  =  \/l  —  sn(z,  fc)2 
dn(z,k)  =  \Jl  —  k2sn(z,k)2 

where  the  roots  take  the  value  1  for  z  =  0.  In  particular,  if  jb  =  0  then  cn(z,  0)  =  cosz 
and  dn(z,0)  =  I,  and  if  k  =  ±1  then  cn(z,k)  =  dn(z,k)  =  1/cosh z.  The  subroutines 
ELLPF  and  ELPFC1  are  available  for  computing  an(z,k)>cn(z,k),  and  dn(z,k)  when  k  is 
a  real  value  such  that  |fc|  <  1.  ELLPF  may  be  used  when  z  is  real  and  ELPFC1  when  z  is 
complex. 


CALL  ELLPF(u,fc,  £,  S, C,  D,IERR) 

It  is  assumed  that  u,  k,  and  £  are  real  numbers  where  Jc2  +  £3  =  1.  S,C,  and  D  are 
real  variables.  When  ELLPF  is  called,  S,C,  and  D  are  assigned  the  values  S  =  sn(u,k), 
C  —  cn(u,k),  and  D  =  dn(u,A:). 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 

IERR  =  0  The  elliptic  functions  were  computed. 

IERR  =  1  (Input  error)  k2  +  £2  1. 

IERR  =  2  u  is  too  large  for  k. 

When  IERR  >  1,  no  computation  is  performed. 

Precision.  Let  K(k)  be  the  complete  elliptic  integral  of  the  first  kind.  For  |ib|  <  .99995  the 
relative  errors  of  sn(u,k)  and  dn(u,  k)  are  less  than  IQ-12  when  0  <  u  <  K(k),  and  the 
relative  error  of  cn(u,k)  is  less  than  10“ 12  when  0  <  u  <  .97^ (Jb). 
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Algorithm.  Let  K  =  K(k)  be  the  complete  elliptic  integral  of  the  first  kind.  For  0  <  u  < 
K/2  (when  £  ^  0),  the  Maclaurin  expansion 

(l  +  fc2)u3  (1  +  14A:2  +  fc4)u6 
sn(u,k)  =  u - — - + - - - 

is  employed  when  u  <  .01.  Otherwise,  if  u  >  .01  let  K'  =  K(£),  q  =  exp(— nK1  / K),  and 
r  =  exp(-irK/K').  Then 


,  ,,  2jt  qn+*  .  (2n+l)jru 


n>0 


is  used  when  k  <  l  and 


sn(u,  k)  = 


2  kK' 


tanh 


+  r  si 
2  K'  ^  1  +  r2n 


n>  1 


(_  l)nr2n  2nu 

sinh  — 


is  used  when  k  >  £.  The  functions  cn(u,k)  and  dn(u,  k)  are  obtained  from 

sn(u,  A:)2  +  cn(u,  A:)2  =  1 
dn\u,  k )2  +  k2sn(u,  k)2  =  1. 


For  K/2  <  u  <  K  the  identities 


sn(u,k)  —  cn(v,k)/dn(v,k) 
cn(u,k)  =  |£|sn(u,  k)/dn(v,  k) 
dn(u,k )  =  \t\/dn(v,k) 

are  applied.  Here  v  =  K  —  u. 

Programming.  ELLPF  employs  the  subroutines  SCD,  SCDF,  SCDJ,  SCDM,  ELLPI, 
SNHCSH  and  functions  ALNREL,  CPABS,  SPMPAR,  IPMPAR.  ELLPF  was  written  by 
Andrew  H.  van  Tuyl  and  modified  by  A.  H.  Morris. 

CALL  ELPFCl(z,fc,£, S,C,  D,IERR) 

The  argument  z  is  complex,  and  k  and  t  are  real  numbers  where  ft2  -f  t2  —  1.  S,C, 

and  D  axe  complex  variables.  When  ELPFC1  is  called  S,  C,  and  D  are  assigned  the  values 
S  =  sn(z,k),  C  —  cn(z,k),  and  D  =  dn(z,k). 


IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 

IERR  =  0  The  elliptic  functions  were  computed. 

IERR  =  1  (Input  error)  A:2  +  £2  ^  1. 

IERR  =  2  z  is  too  large  for  k. 

IERR  =  3  z  is  a  pole  for  the  elliptic  functions. 
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When  IERR  >  1,  no  computation  is  performed. 

Precision.  Let  x  =  Re(z),  y  =  Im(z),  K  =  K[k )  be  the  elliptic  integral  of  the  first  kind 
for  k,  and  K'  =  K (£).  For  |i|  <  .99995  the  relative  errors  of  the  real  and  imaginary  parts 
of  sn(z,  k )  are  less  than  10~12  when  0  <  x  <  K  and  0  <  y  <  .992#',  and  the  relative 
errors  of  the  real  and  imaginary  parts  of  cn(z,k)  and  dn(z,k)  are  less  than  10-12  when 
0  <  x  <  .97 K  and  0  <  y  <  .97 K' . 

Algorithm.  For  z  =  x  +  iy  let 

s  =  sn(x,k)  si  —  sn(y,l) 
c  —  cn(x,  k)  ci  =  cn(y,£) 

d  =  dn(x,  k)  di  =  dn(y,  i) 

and  D  =  c2  +  k2s2s\.  Then 

sn(z,k)  =  ( sdi  +  icdsiCi)/D 
cn(z,  k)  =  (cci  —  isdsidi)/D 
dn(z,k )  =  (dcidi  —  ik2scsi)/D 

are  applied  when  D  ^  0. 

Programming.  ELPFC1  calls  ELLPF,  which  employs  the  subroutines  SCD,  SCDF,  SCDJ, 
SCDM,  ELLPI,  SNHCSH  and  functions  ALNREL,  CPABS,  SPMPAR,  IPMPAR.  ELPFC1 
was  written  by  Andrew  H.  van  Tuyl. 
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WEIERSTRASS  ELLIPTIC  FUNCTION  FOR  THE  EQUIANHARMONIC 

AND  LEMNISCATIC  CASES 


Let  w  and  w'  be  complex  numbers  where  hn(w'/w)  >  0,  and  wmn  =  2 mw  +  2nw'  for  all 
integers  m,  n.  Then  for  any  complex  z,  the  Weierstrass  elliptic  function  P(z-,w,w')  can  be 
defined  by 


P(z]  w,w') 


1 

(z-wmn)2 


where  S'  denotes  the  sum  for  all  m,  n  =  0,  ±1,  ±2,  . . .  except  m  =  n  =  0.  If  w  =  re **  and 
w1  —  r'e*^  where  4>  —  <f>+  9  for  0  <  9  <  2ir,  then  the  restriction  Im(u//u>)  >  0  is  equivalent 
to  assuming  that  0  <  0  <  jr.  P(z-,w,w')  is  analytic  everywhere  except  at  the  points  wmn, 
which  are  poles,  and 

P(z  +  2w,w,w')  =  P(z]w,wl ) 

P(z  +  2w';  w,  w')  =  P(z ;  w,  tv') 
for  all  z.  The  relations 

P{-z\  w,  w')  =  P{z\  w,  w’} 

P(Xz-,Xw,Xw,)  =  X~2P(z]w,wl)  X^O 

also  hold.  A  somewhat  surprising  fact  is  that  only  the  values  g2  =  60E'u;“*  and  gs  = 
140S'u;“®  are  needed  for  computing  P(z;  w,w‘)  at  a  point  z.  Hence,  P(z]  w,  w')  is  frequently 
denoted  by  P(z;g2, £3).  For  A  0 

Sa(A«j,  Att/')  =  A-4<;2  («',«;') 

53(A«;,  Atu')  =  A- 6y3  (w,  tw') 
also  hold.  We  now  consider  the  following  cases: 

(1)  Equianharmonic  (g2  =  0  and  <73  is  a  positive  real  number) 

(2)  Lemniscatic  (g2  is  a  positive  reed  number  and  y3  —  0) 

(1)  occurs  when  2w  =  \  -  and  2xu'  -  \  +  ^t,  and  (2)  occurs  when  2w  =  1  and 
2to'  =  *.  The  following  subroutines  are  available  for  computing  P(z;w,w')  and  its  derivative 
P'(z;  w,w')  for  these  two  choices  of  (u>,  to'). 


CALL  PEQ(z,  e,IERR) 


The  argument  z  is  a  complex  number,  e  is  a  complex  variable,  and  IERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2tw  =  |  -  and  2w'  =  |  +  When  PEQ 
is  called,  if  z  is  not  a  pole  then  IERR  is  assigned  the  value  0  and  e  is  assigned  the  value 
P{z-,w,w'). 


Error  Return.  Ifz  =  wmn  for  some  m,  n  then  IERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  \P[z\w,w')\  <  1  then  the  absolute  error  is  less  than  7  •  10-13.  Otherwise,  the 
relative  error  is  less  than  7  •  10“ 13 . 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 
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CALL  PEQl(z,e, IERR) 

The  argument  z  is  a  complex  number,  e  is  a  complex  variable,  and  IERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2w  =  |  and  2uJ,  =  j  +  -^t.  When  PEQ1 
is  called,  if  z  is  not  a  pole  then  IERR  is  assigned  the  value  0  and  e  is  assigned  the  value 
P'(z;  w,w‘). 

Error  Return.  If  z  =  wmn  for  some  m,n  then  IERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  | P'(z;  w, «;')]  <  1  then  the  absolute  error  is  less  than  7  •  10-13.  Otherwise,  the 
relative  error  is  less  than  7  ■  10“ 13. 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 

References. 

(1)  Eckhardt,  Ulrich,  “Algorithm  549,  Weierstrass’ Elliptic  Functions,"  ACM  Trans.  Math 
Software  4  (1980),  pp. 112-120. 

(2)  _ ,“A  Rational  Approximation  to  Weierstrass’  .P-Function,”  Math  Comp. 

30  (1976),  pp.818-826. 

CALL  P LEM (z,e, IERR) 

The  argument  z  is  a  complex  number,  e  is  a  complex  variable,  and  IERR  is  am  integer 
variable.  It  is  assumed  that  the  periods  are  2w  =  1  and  2w'  =  i.  When  PLEM  is  called,  if 
z  is  not  a  pole  then  IERR  is  assigned  the  value  0  and  e  is  assigned  the  value  P{z]  w,w'). 

Error  Return.  If  z  =  wmn  for  some  m,n  then  IERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  \P(z;  w,  u/)|  <  1  then  the  absolute  error  is  less  than  6  •  10~13.  Otherwise,  the 
relative  error  is  less  than  6  •  10“ 13 . 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 

References. 

(1)  Eckhardt,  Ulrich, “Algorithm  549,  Weierstrass’  Elliptic  Functions,”  ACM Trans.  Math 
Software  4  (1980),  pp. 112-120. 
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(2)  _ ,“A  Rational  Approximation  to  Weierstrass’  P -Function.  II:  The  Lem- 

niscatic  Case,”  Computing  [Arch.  Elektron.  Rechnen )  18  (1977),  pp.  341-349. 

CALL  PLEMl(z,e,IERR) 

The  argument  z  is  a  complex  number,  e  is  a  complex  variable,  and  IERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2w  =  1  and  2tt/'  =  i.  When  PLEMl  is  called,  if 
z  is  not  a  pole  then  IERR  is  assigned  the  value  0  and  e  is  assigned  the  value  P'(z\  w,  u/). 

Error  Return.  If  z  =  wmn  for  some  m,n  then  IERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  \P'(z]w,w')\  <  1  then  the  absolute  error  is  less  than  6*10~1S.  Otherwise,  the 
relative  error  is  less  than  6  •  10-1S. 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 

References. 

(1)  Eckhardt,  Ulrich,  “Algorithm  549,  Weierstrass’  Elliptic  Functions,”  ACM  Trans.  Math 
Software  4  (1980),  pp. 112-120. 

(2)  _ ,“A  Rational  Approximation  to  Weierstrass’  f -Function.  II:  The  Lem- 

niscatic  Case,”  Computing  (Arch.  Elektron.  Rechnen)  18  (1977),  pp.  341-349. 
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INTEGRAL  OF  THE  BIVARIATE  DENSITY  FUNCTION  OVER 
ARBITRARY  POLYGONS  AND  SEMI-INFINITE 
ANGULAR  REGIONS 


Given  a  sequence  of  points  i /,•  =  (z,-,  y»)(*  =  1, . . .  ,  n  +  1)  where  n  >  3  and  i/n+1  =  vx. 
Let  t  denote  the  polygon  whose  boundary  dr  is  a  polygonal  line  which  begins  at  point  i/j, 
traverses  the  points  i \  in  the  order  that  they  are  indexed,  and  is  the  straight  line  segment 
connecting  Vi  to  ui+1  for  each  i  =  1, . . .  ,n  where  vt  #  vi+l.  Then  the  subroutine  VALR2 
is  available  for  computing  the  integral 

r 

and  the  associated  function  A(r )  =  ff  dxdy.  If  the  boundary  dr  is  a  simple  positively 

r 

(negatively)  oriented  closed  curve,  then  P(r )  and  A(t)  are  positive  (negative)  and  |A(r)|  = 
the  area  of  r.  However,  dr  need  not  be  simple.  It  may  be  self-intersecting  or  have  overlap¬ 
ping  line  segments.  If  A0;  is  the  angle  between  the  vectors  i /,•  —  i>i-\  and  i/i+1  —  Vi  (where 
vq  =  vn)  i  then  it  may  occur  that  A <?,-  =  7r  for  some  *,  in  which  case  a  portion  of  the  polygon 
may  be  degenerate.  In  general,  — ir  <  A 0,-  <  r  for  each  t  where  the  sign  of  the  angle  is 
positive  (negative)  if  the  angle  is  measured  in  a  counterclockwise  (clockwise)  direction  from 

n 

Vi  —  Vi_ i  to  Vi+X  —  Vi.  VALR2  also  computes  the  value  fc(r)  =  which  is  an 

*=i 

integer.  If  the  boundary  is  a  simple  closed  curve,  then  k(r)  is  the  winding  number  of  the 
curve  around  any  interior  point  of  the  polygon  r: 

Alternatively,  assume  that  we  are  given  three  points  i =  (z,-,jft)(t  =  1,2,3)  and  let 
A0  denote  the  angle  between  the  vectors  v2  —  v\  and  v$  —  vi.  In  this  case,  assume  that 
the  angle  A 9  is  measured  in  a  counterclockwise  direction  from  1/2  —  V\  to  v$  —  V\,  so  that 
0  <  A0  <  2 ir.  Let  i  denote  the  straight  line  beginning  at  point  vi  and  passing  through  point 
V2,  and  let  £  denote  the  straight  line  beginning  at  V\  and  passing  through  1/3.  Then  the 
subroutine  VALR2  is  also  available  for  computing  P(t)  when  r  is  the  semi-infinite  angular 
region  bounded  by  £  and  £,  and  having  the  angle  A 9.  0  <  P(t)  <  1  for  any  angular  region 
r,  and  P(t )  — »■  1  when  A 9  — *  2n. 

Angular  region  r 


CALL  VALR2(X,  Y, 

The  argument  n  is  either  1  or  the  number  of  points  involved  in  defining  a  polygon. 
If  n  =  1  then  it  is  assumed  that  r  is  a  semi-infinite  angular  region  defined  by  the  points 
Vi  =  (a:,-,  y»)  (»*  =  1,2,3),  and  that  X  and  Y  are  arrays  containing  £1,12,2:3  and  yi,y2,!/3- 
Otherwise,  if  n  ^  1  then  it  is  assumed  that  r  is  a  polygon  defined  by  the  points  1 \  = 
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(xi,  yi )  (i  =  1,  . . . ,  n  +  1)  where  n  >  3  and  vn+i  =  v^.  In  this  case,  X  and  Y  are  arrays 
containing  the  abscissae  x\,  .  ..,xn+x  and  ordinates  yi,  . . . ,  yn+i.  Since  i/n+1  =  u\,  the 
values  sn+i  and  yn+i  need  not  be  supplied  by  the  user.  The  routine  automatically  stores 
xi  and  yi  in  X{n+  1)  and  Y(n  +  1). 

P,  A,  and  k  are  variables.  If  n  =  1  then  P  is  assigned  the  value  P(t)  for  the  angular 
region  r  and  A  is  assigned  the  value  0.  In  this  case,  A:  is  not  defined.  Otherwise,  if  n  >  3 
then  P  is  assigned  the  value  P(r),  A  is  assigned  the  value  A(r),  and  k  is  assigned  the  value 
k(r )  for  the  polygon  r. 

IOP  is  an  input  argument  which  specifies  the  (relative)  precision  to  which  P(r)  is  to 
be  computed.  IOP  is  set  to  1,  2,  or  3  for  3,  6,  or  9  decimal  digit  accuracy. 

IND  is  the  variable  that  reports  the  status  of  the  results.  The  routine  assigns  IND  one 
of  the  following  values: 

IND  =  0  The  desired  values  were  obtained. 

IND  =  1  (Input  error)  V\  is  either  equal  to  v-i  or  1/3,  or  is  too  close  to  1 /2  or 
vz  to  compute  P(r)  for  the  angular  region  r.  In  this  case,  P  is  set 
to  5. 

IND  =  2  The  desired  values  were  obtained.  If  n  =  1  then  A 9  &  jr.  Other¬ 
wise,  if  n  >  3  then  |A0i|  «  jr  for  some  i. 

IND  =  3  (Input  error)  Either  n  <  1  or  n  =  2. 


Remarks.  VALR2  can  be  used  for  computing  the  integral  of  the  general  bivariate  density 
function  over  an  arbitrary  polygon  or  semi-infinite  angular  region  t.  Consider 


exp 


-1 


2(1  -  p») 


W  -  Pu 


O  (^  -  M(g  - /««)  , 


duj  dz 


where  B  —  (1  —  p2)  1/2/(2xcrwcrz),  (p.u,pz)  is  the  mean,  aw  and  az  are  the  (nonzero) 
variances,  and  p  is  the  correlation  coefficient  satisfying  \p\  <  1.  Consider  also 


*=(1  -p2rh 


w  -  Pu  Z  -  pz 

- p - 


and  y  = 


z-  fl2 


Since  this  transformation  maps  straight  lines  into  straight  lines,  t  is  mapped  onto  a  polygon 
or  angular  region  r  and  we  obtain  P(f)  —  P(t).  Moreover,  if  f  is  a  polygon  then  A(f)  = 
Jf  dwdz  =  <Tu<rzyJl  -  p 2  A(r). 

T 

Programming.  VALR2  employs  the  functions  ERF,  ERFC1,  and  SPMPAR.  VALR2  was 
designed  by  Armido  R.  DiDonato  and  Richard  K.  Hageman,  and  modified  by  A.  H.  Morris. 


Reference.  DiDonato,  A.  R.,  and  Hageman,  R.  K.,  Computation  of  the  Integral  of 
the  Bivariate  Normal  Distribution  over  Arbitrary  Polygons,  Report  TR  80-166,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginia,  1980. 
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CIRCULAR  COVERAGE  FUNCTION 


The  subroutine  CIRCV  is  available  for  computing  the  circular  coverage  function  P(R,  d) 
and  the  generalized  circular  error  function  V(K,c).  V  is  the  integral  of  an  uncorrelated 
elliptical  Gaussian  distribution  with  standard  deviations  ax  and  cry  over  a  circle  of  radius 
Kctx  centered  at  the  mean  of  the  distribution.  If  ax  >  av  then 

V(K,  c)  =  1  J“j*  exp  |  [I  +  c2  +  (1  -  c2)  cos  9]  J  r  dr  d9 

where  c  =  oyjax.  P  is  the  integral  of  a  circular  Gaussian  distribution  with  common  standard 
deviation  a  over  a  circle  of  radius  Ra  whose  center  is  offset  a  distance  da  from  the  mean  of 
the  distribution. 

1  fR  f2* 

pm=t*LL  exp 

CALL  Cl RCV(i,  a,  i,  tu,IERR) 

The  argument  i  may  be  any  integer.  If  t  =  0  then  the  arguments  x  and  a  are  assumed 
to  have  the  values  x  =  K  and  a-c  where  K  >  0  and  0  <  c  <  1.  Otherwise,  if  »  ^  0  then 
x  =  R  and  a  —  d  where  R  >  0  and  d  >  0. 

IERR  and  w  are  variables.,.  When  CIRCV  is  called,  if  no  input  errors  are  detected  then 
IERR  is  assigned  the  value  0.  Also,  w  =  V(K,  c )  if  i  =  0  and  w  =  P(R,d)  if  t  ^  0. 

Error  Return.  If  an  input  error  is  detected  then  IERR  is  set  as  follows: 

IERR  =  1  x  >  0  is  not  satisfied. 

IERR  =  2  0<c<lord>0is  not  satisfied. 

When  either  of  these  errors  is  detected,  w  is  assigned  the  value  —1. 

Precision.  CIRCV  is  accurate  to  within  10~6. 

Note.  If  ax  <  av  then  reverse  the  roles  of  x  and  y. 

Programming.  CIRCV  calls  these  functions  ERFO  and  ERFCO.  The  routine  is  an  adapta¬ 
tion  by  A.  H.  Morris  of  the  BASIC  program  CIRCV  given  in  reference  (l). 

References. 

(1)  DiDonato,  A.  R.,  Five  Statistical  Programs  in  BASIC  for  Desktop  Computers, 
Report  NSWC  TR  83-13,  Naval  Surface  Weapons  Center,  Dahlgren,  Virginia,  1982. 

(2)  _ and  Jarnagin,  M.  P.,  A  Method  for  Computing  the  Generalized 

Circular  Error  Function  and  the  Circular  Coverage  Function,  Report  1768,  Naval 
Weapons  Laboratory,  Dahlgren,  Virginia,  1962. 


[{d  +  r  cos  B)2  +  r2  sin2  0]  j  r  dr  d& 
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ELLIPTICAL  COVERAGE  FUNCTION 


The  subroutines  PKILL  and  PKILL3  are  available  for  evaluating  the  integral  of  an 
uncorrelated  elliptical  Gaussian  distribution  over  the  area  A  of  a  circle  (x  -  h)2  +  (y  -  k)2  = 
R2 .  The  probability  to  be  computed  is  given  by 


P(R,c„j„h,k)  P  [-1  + 


dxdy 


where  crx  is  the  standard  deviation  in  the  x  direction  and  (Ty  is  the  standard  deviation  in 
the  y  direction. 

CALL  PKILL(i?,<7Z)cry,/i,  &,p) 

CALL  PK\LLZ{R,<jx,oy,h,k,p) 

R,crx,cry,h,k  are  real  numbers  and  p  is  a  variable.  It  is  assumed  that  R  >  0,  <rx  >  0, 
and  <fy  >  0.  When  PKILL  or  PKILL3  is  called  ,  p  is  assigned  the  value  P{R,crx,(7yjh,k). 

Precision.  PKILL  is  accurate  to  within  10-6  and  PKILL3  is  accurate  to  within  10-3. 

Programming.  PKILL  and  PKILL3  call  the  function  ERFC2.  The  routines  are  adaptations 
by  A.  H.  Morris  of  the  BASIC  programs  ELLCV  and  ELLCV3  given  in  reference  (1). 

References. 

(1)  DiDonato,  A.  R.,  Five  Statistical  Programs  in  BASIC  for  Desktop  Computers , 
Report  TR  83-13,  Naval  Surface  Weapons  Center,  Dahlgren,  Virginia,  1982. 

(2)  _ and  Jarnagin,  M.  P.,  Integration  of  the  General  Bivariate  Distri¬ 

bution  Over  an  Offset  Ellipse ,  Report  1710,  Naval  Weapons  Laboratory,  Dahlgren, 
Virginia,  1960. 


Ill 


COPYING  POLYNOMIALS 


T7V —  1 

If  p(i)  =  ajx3  an<i  the  coefficients  ay  are  stored  in  an  array  A,  then  the  following 
3  = 0 

subroutines  are  available  for  copying  the  first  n  coefficients  ay  into  an  array  B. 

CALL  PLCO P Y(A,  ka,  m,  B,  kb,  n) 

CALL  DPCOPY(A,jfca,m,j3,jfcJ,n) 

A  and  B  are  arrays.  PLCOPY  is  used  if  A  and  B  are  real  arrays,  and  DPCOPY  is 
used  if  A  and  B  are  double  precision  arrays. 

The  arguments  m,  n,  ka,  kb  are  positive  integers.  The  coefficients  ay  are  assumed  to  be 
stored  in  A  where  A(  1  +  j-ka)  =  ay  for  j  =  0,1,  ...,m -1.  The  routine  stores  the  first  n 
coefficients  ay  in  B  where  i5(l  +  j-kb)  =  ay  for  j  =  0, 1,  . . . ,  n  —  1. 

Note.  If  n  >  m  then  B(  1  +  j-kb)  —  0  for  j  >  m. 

Programmer.  A.  H.  Morris 
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ADDITION  OF  POLYNOMIALS 


L—  1  m  —  1 

If  p(x)  =  ajx3  and  q(x)  =  ^  bjXJ  then  the  following  subroutines  are  available  for 

3= 0  3=0 

computing  the  first  n  coefficients  of  the  polynomial  p{x)  +  q{x)  = 

CALL  PADD (A,ka,£,B,kb,m,C,kc,n) 

CALL  D  PADD  (A,  ka,  l,  B,  kb,m,C,  kc,  n) 

A,  B  and  C  are  arrays.  PADD  is  used  if  A,  B  and  C  are  real  arrays  and  DPADD  is 
used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  t,m,n,ka,kb,kc  are  positive  integers.  The  coefficients  a.j  and  bj  are 
assumed  to  be  stored  in  A  and  B  where 

A(1  +  j-ka)  —  aj  (j  =  0, 1,  1) 

J3(l  +j-kb)  =  bj  ( j  =  0,1,  . .  .,m  -  1). 

The  routine  stores  the  first  n  coefficients  cy  of  p(x)  +  g(i)  in  C  where  C(  1  +  j-kc)  =  cj  for 
3  =  0,1,  . . . ,  n  —  1. 

Remarks.  The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same 
location  as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite 
the  input  data  A.  Similarly,  if„C  begins  in  the  same  location  as  B  then  it  is  assumed  that 
kc  =  kb.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then.it  is  assumed 
that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 

Programmer.  A.  H.  Morris 
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SUBTRACTION  OF  POLYNOMIALS 


t—  1  TTl  —  1 

If  p(x )  =  a.jX 3  and  q(x)  =  bjX3  then  the  following  subroutines  are  available  for 

3=0  j-0 

computing  the  first  n  coefficients  of  the  polynomial  p(x)  —  q(x)  —  CjXJ. 

CALL  PS UBT (A,  ka,£,B,  kb,  m, C,  kc,  n) 

CALL  DPSUBT (A,  ka,  £,  B,  kb,m,C,  kc,  n) 

A,  B  and  C  are  arrays.  PSUBT  is  used  if  A,  B  and  C  are  real  arrays  and  DPSUBT  is 
used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  £,m,n,ka,kb,kc  are  positive  integers.  The  coefficients  a3  and  b3  are 
assumed  to  be  stored  in  A  and  B  where 

A(1  +  j-ka)  =  ay  (j  =  0, 1,  1) 

B(1  +  j-kb)  —  bj  (j  =  0,1,  1). 

The  routine  stores  the  first  n  coefficients  c3  of  p(x)  —  q(x)  in  C  where  C(  1  +  j-kc)  —  c3  for 

J  =  0,1, 

Remarks.  The  eirray  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same 
location  as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite 
the  input  data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that 
kc  —  kb.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed 
that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 

Programmer.  A.  H.  Morris 
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MULTIPLICATION  OF  POLYNOMIALS 

t—  1  m — 1 

If  p(i)  =  ajxJ  and  <l[x)  =  52  bjX1  then  the  following  subroutines  are  available  for 

3=0  j'=0 

computing  the  first  n  coefficients  of  the  polynomial  p(x)g(z)  =  52jc3x*  ■ 

CALL  PM U LT(A,  ka,  i,  B,kb,  m,  C,  kc,  n) 

CALL  DPMULT(A,  ka,  i,  B,kb,  m,  C,  kc,  n) 

A,  B  and  C  are  arrays.  PMULT  is  used  if  A,  B  and  C  are  real  arrays  and  DPMULT 
is  used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  i,m,n,ka,kb,kc  are  positive  integers.  The  coefficients  ay  and  bj  are 
assumed  to  be  stored  in  A  and  B  where 

A(l  +  j-ka)  =  ay  (j  =  0, 1,  1) 

B(l  +  j-kb)  =  bj  (j  =  0,1,  . ..  ,m  —  1). 

The  routine  stores  the  first  n  coefficients  cy  of  p(x)q(x)  in  C  where  C(  1  +  j  -kc)  =  cy  for 
j  =  0,1,  ...  ,n  -  1. 

Remarks.  It  is  assumed  that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 

Programmer.  A.  H.  Morris 
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DIVISION  OF  POLYNOMIALS 


L—  1  m  — 1 

If  p(z)  =  Z)  aixi  and  ?(*)  =  T,  bjX3  where  b0  ^  0,  then  the  following  subroutines 
i=o  j'=o 

are  available  for  computing  the  first  n  coefficients  of  the  series  p(x)/q(x)  =  cDxK 

CALL  PD  IV(A,  ka,  l,  B,  kb,  m,  C,  kc,  n,IERR) 

CALL  D  P  D I V( A,  ka,l,B,  kb,  m,  C,  kc,  n.IERR) 

A,  B  and  C  are  arrays.  PDIV  is  used  if  A,  B  and  C  are  real  arrays  and  DPDIV  is 
used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  £,m,n,ka,  kb,kc  are  positive  integers.  The  coefficients  ay  and  6y  are 
assumed  to  be  stored  in  A  and  B  where 

A(1  +  j'ka)  =  ay  (j  =  0,1,  1) 

B(l+  j-kb)  -  bj  (j  =  0,1,  ...,m- 1). 

IERR  is  a  variable.  When  the  routine  is  called,  if  60  #  0  then  IERR  is  assigned  the  value 
0  and  the  first  n  coefficients  cy  of  p(x)/q(x)  are  stored  in  C  where  C(  1  +  j-kc )  =  cy  for 
i  =  0,l,  ...,n-  1. 

Error  Return.  IERR  =  1  if  &o  =  0.  In  this  case,  no  computation  is  performed. 

Remarks.  It  is  assumed  that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 
Programmer.  A.  H.  Morris 
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REAL  POWERS  OF  POLYNOMIALS 


m  — 1 

If  r  is  real  and  p(x)  =  22  a,jX 1  where  ao  >  0,  then  the  following  subroutines  are 

3=0  . 

available  for  computing  the  first  n  coefficients  of  the  series  p(x)r  =  223  bjX3 . 

CALL  PLPWR(r,  A,fca,m,  B,kb,  n,IERR) 

CALL  DPLPWR(r,  A, ka,  m,  B,  kb,  n,IERR) 

A  and  B  are  arrays.  PLPWR  is  used  if  A  and  B  are  real  arrays  and  r  a  real  number, 
and  DPLPWR  is  used  if  A  and  B  are  double  precision  arrays  and  r  a  double  precision 
number. 

The  arguments  m,  n,  ka,kb  are  positive  integers.  The  coefficients  ay  are  assumed  to  be 
stored  in  A  where  A(1  +j-ka)  =  a,  for  j  =  0, 1,  . . .  ,m  -  1.  IERR  is  a  variable.  When  the 
routine  is  called,  if  a0  >  0  then  IERR  is  assigned  the  value  0  and  the  first  n  coefficients  bj 
of  p(x)r  are  stored  in  B  where  5(1  +  j-kb)  =  bj  for  j  =  0, 1,  . . . ,  n  -  1. 

Error  Return.  IERR  =  1  if  ao  <  0.  In  this  case,  no  computation  is  performed. 

Remark.  It  is  assumed  that  the  arrays  A  and  B  do  not  overlap. 

Algorithm.  If  g  =  pr  then  pq'  =  rqp1  where  p‘  and  q'  are  the  derivatives  of  p  and  q. 

3 

Consequently,  bj  =  ^  £  (r*  + 1  -  j)ajbj is  used  for  j  >  1.  Also  b0  =  a^. 

i=l 

Programmer.  A.  H.  Morris 
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INVERSES  OF  POWER  SERIES 


Given  an  analytic  function  w  =  f(z)  =  ^  a^z*  where  /(0)  =  0.  Then  the  inverse 

»>i 

function  z  —  f~1(w)  exists  when  ai  7^  0,  and  f~1(w)  =  duo*.  The  subroutines  PINV 

»>i 

and  DPINV  are  available  for  obtaining  the  coefficients  dj  when  the  coefficients  are  real. 
DPINV  is  a  double  precision  routine. 

CALL  PINV(A,D,n,WK) 

CALL  DPINV(A,  D,  n,WK) 

If  PINV  is  called  then  A ,  D,  and  WK  are  real  arrays.  Otherwise,  if  DPINV  is  called 
then  A,  D,  and  WK  are  double  precision  arrays. 

It  is  assumed  that  n  >  2.  A  is  an  array  containing  the  coefficients  «i,  . . .  ,an  and  D  is 
an  array  of  dimension  n.  When  PINV  or  DPINV  is  called,  the  coefficients  d\,  ...  ,dn  are 
computed  and  stored  in  D. 

WK  is  an  array  of  dimension  n(n  +  l)/2  or  larger.  WK  is  a  work  space  for  the  routine. 
Programmer.  A.  H.  Morris 

Reference.  Chang,  Feng-cheng, “Power  Series  Unification  and  Reversion,”  Applied  Math 
and  Computation  23  (1987),  pp.  7-23. 
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DERIVATIVES  AND  INTEGRALS  OF  POLYNOMIALS 


n  — 1 

Let  f(x)  =  5Z  a<x'  be  a  polynomial  with  real  coefficients  a 
*=o 

differentiated  and  integrated  by  the  following  subroutine: 

CALL  MPLNMV(MO,x0,  n,  A,  w) 

A  is  an  array  containing  the  coefficients  o»  where  A(t)  = 
argument  xq  is  an  arbitrary  real  number  and  w  is  a  variable. 
—1,0, 1,2.  When  MPLNMV  is  called  w  is  assigned  the  value: 

Io°f(x)  dx  MO  =  -1 

_J  /(* 0)  if  MO  =  0 

W~  f'(x 0)  if  MO  =  1 

.  f"{x 0)  if  MO  =  2 

Programmer.  Allen  V.  Hershey 


i.  The  polynomial  can  be 


for  i  =  1,  . . .  ,n.  The 
MO  may  have  the  values 
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EVALUATION  OF  CHEBYSHEV  EXPANSIONS 

For  any  complex  number  z  and  integer  n  =  0, 1,  . . .  let 

T0(z)  =  1,  Tiiz)  =  z 
Tn+j(z)  =  2zTn+1{z)  —  Tn[z). 

Then  Tn(z)  is  a  polynomial  of  degree  n  having  the  leading  coefficient  2n_1  when  n  >  1. 
Also  Tn(i)  =  cos(nfl)  when  t  =  cos 0(0  <  0  <  w),  so  that  |Tn(i)|  <  1  for  real  t  where 
|t|  <  1.  The  polynomials  Tn(z)  are  called  the  Chebyshev  polynomials  (of  the  first  kind).  If 

r»-l 

f(x)  =  aoj2+  aiTi(x)  where  a»  is  real,  then  the  following  functions  are  available  for 
1=1 

computing  f(x)  when  x  is  real. 

CSEVL(z,  A,n) 

It  is  assumed  that  n  >  1  and  that  A  is  an  array  containing  oo,oi,  . where 
A(:)  =  a,-i(i  =  1,  .. .  ,n).  Then  CSEVL(z,  A,  n)  =  f(x)  for  any  real  x. 

Programmer.  A.  H.  Morris 

DCSEVL(z,A,n) 

It  is  assumed  n  >  1  arid  that  A  is  a  double  precision  array  containing  ao,  a1;  . . . ,  an_i 
where  A(i)  =  =  1,  . . . ,  n).  Then  for  any  double  precision  value  x,  DCSEVL(a:,  A,  n) 

is  the  double  precision  value  of  f(x). 

Remark.  DCSEVL  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  A.  H.  Morris 


129 


LAGRANGE  POLYNOMIALS 

Let  a\,  . . .  ,an  be  n  distinct  real  numbers.  Then  the  iih  Lagrange  polynomial  is  defined 

by 

_  ( x  -  ai)(g  -  a8)  •  •  ■  (x  -  at-i)(x  -  a,+i)  • • •  (x  -  an) 

(a»  —  ai)(a<  —  <12)  •  •  •  (a*  —  a«-i)(a*  —  a*+i)  •  •  •  (a*  —  an) 

for  t  =  1, 2,  . . . ,  n.  The  Lagrange  polynomials  have  the  property  that  &(a,-)  =  1,  =  0 

n 

for  j  ^  i,  and  p(x)  =  Y  p{a*)<f>i{x)  for  any  polynomial  of  degree  n  —  1.  For  convenience, 
»=i 

di  =  (a»  -  ai)(ai  -  a^)  •  •  •  (a,-  -  aj_i)(a,-  -  a,+x)  •  •  •  (ai  -  are) 

is  called  the  normalization  divisor  of  <f>i(x).  The  following  subroutines  are  available  for 
computing  the  Lagrange  polynomials  and  their  normalization  divisors. 

CALL  LGRNGN(A,n,  D) 

A  and  D  are  arrays  of  dimension  n.  The  arguments  ax, _ ,an  are  given  in  the  array 

A.  The  normalization  divisors  di,  ...  ,dn  are  computed  by  the  routine  and  stored  in  D. 

Programmer.  Allen  V.  Hershey 

CALL  LGRNGV(MO,n,  i0,  A,  D,  F,DF,DDF) 

A  and  D  are  arrays  of  dimension  n.  The  arguments  ai,  ...,an  are  given  in  A  and 
the  normalization  divisors  di ,  . . . ,  d„  are  given  in  D.  The  argument  is  an  arbitrary  real 
number  and  F,DF,DDF  are  arrays  of  dimension  n. 

The  argument  MO  may  take  the  values  0, 1, 2.  If  MO  =  0  then  the  polynomials 
are  evaluated  at  xo  and  the  values  &(xo)  stored  in  F.  If  MO  =  1  then  the  function  &(x) 
and  its  derivative  $(x)  are  computed  at  xo.  In  this  case,  <^,(xo)  is  stored  in  F(i)  and  ^(xo) 
is  stored  in  DF(i')  for  t  =  1,  ...,n.  Similarly,  if  MO  =  2  then  the  function  and  its 
first  and  second  derivatives  are  computed  at  xo.  The  values  <fo(xo)  are  stored  in  F,  the  first 
derivatives  are  stored  in  DF,  and  the  second  derivatives  are  stored  in  DDF. 

Note.  If  MO  =  0  then  DF  and  DDF  are  ignored  by  the  routine.  Similarly,  if  MO  =  1  then 
DDF  is  ignored. 

Programmer.  Allen  V.  Hershey 

CALL  LGRNGX(A,  n,C) 

A  is  an  array  of  dimension  n  and  C  an  array  of  dimension  n  x  (n  + 1).  The  arguments 
ai,  . . .  ,an  are  given  in  A.  The  purpose  of  the  routine  is  to  compute  the  coefficients  c,y  of 
the  Lagrange  polynomials 

n  —  1 

k= 0 
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When  LGRNGX  is  called,  the  coefficients  of  <f>3(x)  are  stored  in  the  jth  column  of  C  for 
j  <  n.  Also,  the  first  n  coefficients  of  the  polynomial 

g(x)  =  (x  -  a*)  ■  •  •  (x  -  an) 

are  stored  in  the  (n  +  l)8t  column  of  C. 

Programmer.  Allen  V.  Hershey 
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ORTHOGONAL  POLYNOMIALS  ON  FINITE  SETS 


Let  uj,  be  n  distinct  real  numbers.  For  any  real-valued  functions  /^defined 

on  the  points  u;  let  [f,g)  =  Y  Then  (f,g)  is  an  inner  product  when  /  and 

t=i 

g  are  regarded  as  functions  defined  only  on  u».  Thus,  an  orthonormal  set  of  polynomials 
{4>o,4>i,  1}  exists  where  the  degree  of  <j>}-  is  j  for  j  <  n.  The  polynomials  <j>j  are 

defined  recursively  by 


<t>i+i(u)  =  7"  [(«  ~  bj)<f>Au)  ~ 

a3 

where  a j  =  (<f>j+1,u<f>j)  and  bj  =  (<£y,u0y).  Here  it  is  assumed  that  <j>^x  =  o_x  =  0  and 
4>o(u)  =  1  jy/n.  The  following  subroutines  are  available  for  computing  these  polynomials. 

CALL  ORTHOS (U,m,P,n,R) 

U  is  an  array  containing  the  values  uj,  . . . ,  u„  and  m  is  an  integer  such  that  1  <  m  <  n. 
P  is  an  array  of  dimension  n  x  m  and  R  an  array  of  dimension  2m  -  2.  When  ORTHOS  is 
called,  is  computed  and  stored  in  P{i,j)  for  i  <  n  and  j  <  m.  Also  the  coefiicients 

do,  60,  di,  61,  . . .  ,am_2,6m_2  are  stored  in  R. 

Programmer.  Allen  V.  Hershey. 

CALL  0RTH0V(M0,n,u,  R, m,  F,DF,DDF) 

The  argument  u  is  a  real  number  and  m  an  integer  such  that  1  <  m  <  n.  R  is  an 
array  containing  the  coefiicients  a0,6o, ai, . . .  ,am_2,6m_2  and  F’,DF,DDF  are  arrays  of 
dimension  m. 

MO  may  take  the  values  0,1,2.  If  MO  =  0  then  are  evaluated  at 

u  and  the  values  <f>j- i(u)  stored  in  F.  If  MO  =  1  then  4>j-i  and  its  derivative  4>Yi  are 
computed  at  u.  In  this  case,  ^^(u)  is  stored  in  F(j)  and  is  stored  in  DF(jt') 

for  j  —  1,  . . . ,  m.  Similarly,  if  MO  =  2  then  4>j-i  and  its  first  and  second  derivatives  are 
evaluated  at  u.  The  values  are  stored  in  F,  the  first  derivatives  are  stored  in  DF, 

and  the  second  derivatives  are  stored  in  DDF. 

Note.  If  MO  =  0  then  DF  and  DDF  are  ignored  by  the  routine.  Similarly,  if  MO  =  1  then 
DDF  is  ignored. 

Programmer.  Allen  V.  Hershey. 
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CALL  ORTHO X(n,  R,  m,  C ) 

The  argument  m  is  an  integer  such  that  1  <  m  <  n.  R  is  an  array  containing  the 
coefficients  ao, 6o>  ai>  &i ,  •  •  • ,  am- 2,  bm- 2  and  C  an  array  of  dimension  m  X  m.  The  purpose 
of  the  routine  is  to  compute  the  coefficients  c,y  of  each  polynomial 

m— 1 

0y-l(u)  =  Ck+lijuk  (j  =  1,  . . . ,  m). 

k=0 

When  ORTHOX  is  called,  the  coefficients  of  are  stored  in  the  jtfl  column  of  C. 
Programmer.  Allen  V.  Hershey 
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ZEROS  OF  CONTINUOUS  FUNCTIONS 


Let  F(x)  be  a  continuous  real- valued  function  defined  for  a  <  x  <  b,  and  assume  that 
.F(a)  and  F(b)  have  opposite  signs.  Then  the  following  function  is  available  for  finding  a 
point  x  in  the  interval  [a,  b ]  for  which  F{x)  —  0. 

ZEROIN(F,a,5,AERR,RERR) 

ZERO  IN  returns  a  value  x  in  the  interval  [o,6]  for  which  E(z)  =  0.  AERR  and  RERR 
are  absolute  and  relative  tolerances  that  specify  the  desired  accuracy  of  x.  It  is  assumed 
that  AERR  >  0  and  RERR  >0.  If  xq  is  the  zero  of  F  being  approximated  by  x,  then 
ZEROIN  terminates  when  a  value  x  is  obtained  for  which  it  is  estimated  that  \x  —  xo\  < 
RERR  |zo|  +  AERR  is  satisfied. 

Note.  The  function  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

Programming.  ZEROIN  is  a  slightly  modified  translation  of  the  ALGOL  60  procedure 
ZERO  given  in  reference  (1).  The  code  was  distributed  by  G.  E.  Forsythe,  M.  A.  Malcolm, 
and  C.  B.  Moler  (University  of  New  Mexico),  and  modified  by  A.  H.  Morris.  The  function 
SPMPAR  is  called. 

References. 

(1)  Brent,  Richard,  Algorithms  for  Minimization  without  Derivatives,  Prentice-Hall, 
1973. 

(2)  Forsythe,  G.E.,  Malcolm,  M.A.,  and  Moler,  C.B.,  Computer  Methods  for  Mathemat¬ 
ical  Computations,  Prentice-Hall,  1977. 
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SOLUTION  OF  SYSTEMS  OF  NONLINEAR  EQUATIONS 

Let  fi(x)  =  0  (j  =  l,...,n)  denote  a  system  of  n  equations  in  n  unknowns  where 
x  =  (xi,  ...,xn).  Assume  that  each  /,(x)  is  differentiable  and  that  an  initial  guess  a  = 
(al5  . . . ,  an)  to  a  solution  of  the  equations  is  given.  Then  the  following  subroutine  is  available 
for  solving  the  equations  to  within  a  specified  tolerance. 

CALL  HBRD(F,  n, X, FVEC, EPS, TOL, INFO, WK,£) 

X  and  FVEC  are  arrays  of  dimension  n  or  larger.  On  input  X  contains  the  start¬ 
ing  point  a  =  (ax,  .. .  ,  a„).  When  HBRD  terminates,  X  contains  the  final  estimate  x  = 
(xx ,  . . , ,  xn)  of  the  solution  vector  and  FVEC  contains  the  values  of  the  functions  f\ , 
at  the  output  point  in  X. 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  FVEC, IFLAG) 

Here  X  and  FVEC  are  arrays  of  dimension  n  and  IFLAG  is  an  integer  variable.  The  array 
X  contains  a  point  x  =  (xx,  ...,xn).  Normally  F  will  evaluate  the  functions  /x,  ...,/„ 
at  this  point  and  store  the  results  in  FVEC.  However,  if  x  does  not  lie  in  the  domain  of 
/x,  •••,  fn  then  this  cannot  be  done.  In  this  case,  the  argument  IFLAG  (which  will  have 
been  assigned  a  nonnegative  value  by  HBRD)  should  be  reset  by  F  to  a  negative  value. 
This  will  signal  HBRD  to  terminate.  F  must  be  declared  in  the  calling  program  to  be  of 
type  EXTERNAL. 

EPS  is  an  input  argument  which  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  accurate  to  k  significant  decimal  digits  then  one 
may  set  EPS  =  10-fc.  It  is  required  that  EPS  >  0.  If  EPS  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

TOL  is  an  input  argument  which  specifies  the  desired  accuracy  of  the  solution.  The 
Euclidean  norm  ||x||  =  >/E,-x?  is  employed.  If  x  denotes  an  actual  solution  of  the  equations, 
then  HBRD  terminates  when  an  iterate  x  is  generated  for  which  it  is  estimated  that  ||x  — 
x\\  <  TOL  •  ||x||  is  satisfied.  It  is  required  that  TOL  >  0.  In  order  for  the  convergence  test 
to  work  properly,  it  is  recommended  that  TOL  always  be  smaller  than  10~s. 

WK  is  an  array  of  dimension  £  that  is  used  for  a  work  space.  It  is  assumed  that  the 
argument  £  is  greater  than  or  equal  to  n(3n  +  13)/2. 

INFO  is  an  integer  variable  that  reports  the  status  of  the  results.  When  HBRD  termi¬ 
nates,  INFO  has  one  of  the  following  values: 

INFO  <  0  This  occurs  when  the  user  terminates  the  execution  of  HBRD  by 
resetting  the  argument  IFLAG  in  the  subroutine  F  to  a  negative 
value.  Then  INFO  =  the  negative  value  of  IFLAG. 

INFO  =  0  (Input  Error)  n  <  1,  EPS  <  0,  TOL  <  0,  or  £  <  n(3n  +  13) /2. 

INFO  =  1  A  solution  having  the  desired  accuracy  was  obtained. 
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INFO  =  2  The  number  of  calls  to  the  subroutine  F  has  reached  or  exceeded 
200(n  +  1). 

INFO  =  3  TOL  is  too  small.  No  further  improvement  in  the  accuracy  of  x  is 
possible. 

INFO  =  4  The  routine  is  making  very  poor  progress. 

When  HBRD  terminates,  if  INFO  ^  0  then  X  contains  the  final  iterate  that  was  gener¬ 
ated.  Also,  if  INFO  >  1  then  FVEC  contains  the  values  of  the  functions  f\,  ...  ,fn  at  this 
iterate.  If  INFO  =  2  then  it  may  be  helpful  to  continue  the  procedure  by  recalling  HBRD 
with  the  current  point  in  X  as  the  new  starting  point.  However,  this  is  not  advisable  when 
INFO  =  4.  This  setting  can  arise  when  x  =  0  is  a  solution  or  when  entrapment  occurs. 
HBRD  searches  for  a  solution  to  the  equations  by  minimizing  ^  /«(*)*•  In  doing  this,  it 
can  become  trapped  in  a  region  where  the  minimum  does  not  correspond  to  a  solution  of 
the  equations.  This  is  what  occurs  when  the  equations  have  no  solution.  When  entrapment 
occurs  and  the  equations  are  known  to  have  a  solution,  then  it  is  recommended  that  the 
user  try  a  different  starting  point. 

Scaling.  If  the  convergence  criterion  ||z  —  x||  <  TOL  •  ||z|j  is  satisfied  and  TOL  =  10-fc, 
then  the  larger  components  of  the  final  iterate  x  may  be  accurate  to  A;  significant  digits  but 
not  the  smaller  components.  For  example,  if  TOL  =  10-s  and  x  =  (1.2,.34E-4),  then  1.2 
may  be  accurate  to  5  significant  digits  while  .34E-4  is  accurate  to  only  1  significant  digit. 
If  it  is  suspected  that  the  smaller  components  do  not  have  acceptable  accuracy,  then  it  is 
recommended  that  the  variables  in  the  original  problem  be  rescaled  and  the  problem  rerun. 

Algorithm.  A  modified  form  of  the  hybrid  Powell  procedure  is  employed. 

Programming.  HBRD  is  a  slightly  modified  version  of  the  MINPACK-1  subroutine  HY- 
BRD1.  The  MINPACK-1  subroutines  HYBRD,  ENORM,  DOGLEG,  FDJAC1,  QFORM, 
QRFAC,  R1MPYQ,  and  R1UPDT  are  employed.  The  subroutines  were  written  by  Jorge  J. 
More,  Burton  S.  Garbow,  and  Kenneth  E.  Hillstrom  (Argonne  National  Laboratory).  The 
function  SPMPAR  is  also  used. 

References. 

(1)  More,  J.  J.,  Garbow,  B.S.,  and  Hillstrom,  K.  E.,  User  Guide  for  MINPACK-1 , 
Argonne  National  Laboratory  Report  ANL-80-74,  Argonne,  Illinois,  1980. 

(2)  Powell,  M.  J.D.,  “A  Hybrid  Method  for  Nonlinear  Equations,”  Numerical  Methods 
for  Nonlinear  Algebraic  Equations,  P.  Rabinowitz  (ed.),  Gordon  and  Breach,  Lon¬ 
don,  1970. 
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SOLUTIONS  OF  QUADRATIC,  CUBIC,  AND  QUARTIC  EQUATIONS 


Given  a  polynomial  ao  +  ai z  +  •  ■  ■  +  anzn  with  real  coefficients  where  an  ^  0  and 
n  =  2,3  or  4.  The  following  subroutines  are  available  for  computing  the  roots  z\,  . . .  ,zn  of 
the  polynomial. 

CALL  QDCRT(A,  Z) 

CALL  CBCRT(A,  Z) 

CALL  QTCRT(A, Z) 

It  is  assumed  that  A  is  a  real  array  and  Z  a  complex  array.  QDCRT  is  used  if  n  =  2, 
CBCRT  is  used  if  n  =  3,  and  QTCRT  is  used  if  n  =  4.  A  is  the  array  of  coefficients 
where  A(fc)  =  a,k~i  for  k  =  1, 2,  . . . ,  n  +  1,  and  Z  is  an  array  of  dimension  n.  When  the 
appropriate  subroutine  is  called,  the  roots  ,  . . . ,  zn  are  stored  in  Z.  The  real' roots  precede 
the  complex  roots.  The  real  roots  are  ordered  so  that  |z3  |  <  |z3+1J.  The  complex  roots  are 
unordered  except  that  complex  conjugate  pairs  of  roots  appear  consecutively  with  the  root 
having  the  positive  imaginary  part  being  first. 

Programming.  QTCRT  calls  the  subroutines  CBCRT  and  AORD,  and  CBCRT  calls  the 
subroutine  QDCRT  and  function  CBRT.  The  routines  were  written  by  A.  H.  Morris  and 
CBCRT  was  modified  by  Wm.  Davis  (NSWC).  The  function  SPMPAR  is  also  used. 

CALL  DQDCRT(A,ZR,ZI) 

CALL  DCBCRT(A,ZR,ZI) 

CALL  DQTCRT(A,ZR,ZI) 

It  is  assumed  that  A,ZR,  and  ZI  are  double  precision  arrays.  DQDCRT  is  used  if  n  =  2, 
DCBCRT  is  used  if  n  —  3,  and  DQTCRT  is  used  if  n  =  4.  A  is  the  array  of  coefficients 
where  A(k )  =  a*_  i  for  k  =  1,2,  . . . ,  n  + 1,  and  ZR  and  ZI  are  arrays  of  dimension  n.  When 
the  appropriate  subroutine  is  called,  the  real  parts  of  the  roots  zu  ...,zn  are  stored  in  ZR 
and  the  imaginary  parts  are  stored  in  ZI.  The  real  roots  precede  the  complex  roots.  The 
real  roots  are  ordered  so  that  zy  <  |zy+i|.  The  complex  roots  are  unordered  except  that 
complex  conjugate  pairs  of  roots  appear  consecutively  with  the  root  having  the  positive 
imaginary  part  being  first. 

Programming.  DQTCRT  calls  the  routines  DAORD,  DCSQRT,  and  DCBCRT.  DCBCRT 
calls  the  subroutine  DQDCRT  and  function  DCBRT.  The  routines  were  written  by  A.  H. 
Morris.  The  function  DPMPAR  is  also  used. 
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DOUBLE  PRECISION  ROOTS  OF  POLYNOMIALS 

Given  a  polynomial  a0  +aiz-\ - \-anzn  of  degree  n  >  1.  The  subroutines  DRPOLY 

and  DCPOLY  are  available  for  obtaining  the  roots  zlt  ...,zn  of  the  polynomial.  DRPOLY 
may  be  used  if  the  coefficients  a,  are  real,  and  DCPOLY  is  applicable  if  the  coefficients  are 
complex.  These  subroutines  perform  the  calculations  in  double  precision. 

CALL  DRPOLY(A,n,ZR,ZI,NUM,WK,DWK) 

A  is  a  double  precision  array  containing  the  coefficients  where  A(j)  =  an_J+1  for 
j  —  1  j  . . . ,  n  + 1.  ZR  and  ZI  are  double  precision  arrays  of  dimension  n  or  larger,  and  NUM 
is  an  integer  variable.  When  DRPOLY  is  called,  if  no  errors  are  detected  then  NUM  =  the 
number  of  roots  that  are  obtained.  If  NUM  >  1  then  the  real  parts  of  the  roots  are  stored  in 
ZR(j)  and  the  imaginary  parts  in  ZI(j)  for  j  =  1,  . . .  ,NUM.  The  roots  are  unordered  except 
that  complex  conjugate  pairs  of  roots  appear  consecutively  with  the  positive  imaginary  part 
being  first. 

WK  is  a  real  array  of  dimension  n  +  1  or  larger,  and  DWK  is  a  double  precision  array 
of  dimension  6(n  +  1)  or  larger.  WK  and  DWK  are  work  spaces  for  the  routine. 

Error  Return.  NUM  =  -1  if  n  <  1  or  an  =  0. 

Programming.  DRPOLY  employs  the  subroutines  DRPLY1,FXSHFR,QUADIT,REALIT, 
CALCSC,  NEXTK,  NEWEST,  QUADSD,  and  QUADPL.  These  routines  exchange  infor¬ 
mation  in  a  labeled  common  block  named  GLOBAL.  The  routines  were  written  by  M.  A. 
Jenkins  (Queen’s  University,  Kingston,  Ontario),  and  modified  by  A.  H.  Morris.  The  func¬ 
tions  SPMPAR,  DPMPAR,  and  IPMPAR  are  also  used. 

References. 

(1)  Jenkins,  M.  A., “Zeros  of  a  Real  Polynomial,”  ACM  Trans.  Math  Software  1  (1975), 
pp.  178-189. 

(2)  Jenkins,  M.  A.  and  Traub,  J.  F.,“A  Three-Stage  Algorithm  for  Real  Polynomials  using 
Quadratic  Iterations,”  SIAM  J.  Numerical  Analysis  7  (1970),  pp.  545-566. 


CALL  DCPOLY(AR,AI,n,ZR,ZI,NUM,DWK) 

AR  and  AI  are  double  precision  arrays  containing  the  real  and  imaginary  parts  of  the 
coefficients  where  AR(j)  =  Re(an_i+1)  and  AI(j')  =  Im(an_i+1)  for  j  =  1,  . . . ,  n  +  1.  ZR 
and  ZI  are  double  precision  arrays  of  dimension  n  or  larger,  and  NUM  is  an  integer  variable. 
When  DCPOLY  is  called,  if  no  errors  are  detected  then  NUM  =  the  number  of  roots  that 
are  obtained.  If  NUM  >  1  then  the  rezil  parts  of  the  roots  are  stored  in  ZR(j)  and  the 
imaginary  parts  in  ZI(j)  for  j  =  1, . . .  ,NUM. 

DWK  is  a  double  precision  array  of  dimension  10(n  +  1)  or  larger  that  is  a  work  space 
for  the  routine. 
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Error  Return.  NUM  =  -1  if  n  <  1  or  an  =  0. 

Programming.  DCPOLY  employs  the  routines  DCPLY1,  CAUCHY,  NOSHFT,  FXSHFT, 
VRSHFT,  CALCT,  NEXTH,  POLYEV,  CDIVID,  and  the  functions  SCALCP,  ERREV. 
These  routines  and  functions  were  written  by  M.A.  Jenkins  (Queen’s  University,  Kingston, 
Ontario)  and  J.  F.  Traub  (Bell  Laboratories),  and  modified  by  A.  H.  Morris.  The  functions 
DPMPAR,  IPMPAR,  and  DCPABS  are  also  used. 

References. 

(1)  Jenkins,  M.  A.  and  Traub,  J.  F.,  “Algorithm  419,  Zeros  of  a  Complex  Polynomial,” 
Comm.  ACM  15  (1972),  pp.  97-99. 

(2)  _ ,  “A  Three-Stage  Variable-Shift  Iteration  for  Polynomial  Zeros  and  its  Relation 

to  Generalized  Rayleigh  Iteration,”  Numer.  Math  14  (1970), pp.  252-263. 
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ACCURACY  OF  THE  ROOTS  OF  A  REAL  POLYNOMIAL 


Given  a  polynomial  p(z )  =  a0  +  a\z  H - h  anzn  of  degree  n  >  1  with  real  coefficients. 

Let  zi,  ...  ,zn  be  approximations  for  the  roots  of  p(z).  Then  for  each  z,-,  the  subroutine 
RBND  obtains  the  radius  rt-  of  a  disk  D{  =  {z  :  \z  —  z,-|  <  r,}  centered  at  z»  which  contains 
a  true  zero  of  the  polynomial.  The  radius  r»  is  an  upper  bound  on  the  absolute  error  of  the 
approximation  z,-. 

For  each  z»,  RBND  also  computes  the  number  ki  of  disks  Dj  (including  the  disk  Di) 
which  overlap  with  D,.  The  value  ki  is  the  number  of  roots  of  p(z)  that  are  clustered  near 
Zi.  If  ki  =  1  then  z»  approximates  a  simple  root. 

Example.  In  the  figure 
k\  —  1,  /c2  =  3,  k$  =  2, 
and  =  2. 


CALL  RBND(n,  A,  2,i2,RERR,Ff ,IERR) 

A  is  a  real  array  containing  the  coefficients  a0,ai,  ...,an  and  Z  a  complex  array 
containing  the  approximate  roots  Zi,  ...,zn.  It  is  assumed  that  n  >  1  and  A(i)  =  at_x  for 
*  =  1,  . . . ,  n  +  1. 

IERR  is  an  integer  variable,  R  a  real  array  of  dimension  n  or  larger,  and  K  an  integer 
array  of  dimension  n  or  larger.  When  RBND  is  called,  if  no  input  errors  are  detected  then 
IERR  is  assigned  the  value  0,  the  radii  rj,  . . .  ,rn  are  computed  and  stored  in  R,  and  the 
values  ki,  . . . ,  kn  are  computed  and  stored  in  K. 

RERR  is  a  real  array  of  dimension  n  or  larger.  If  z^  =  0  then  RERR(t)  is  set  to  -1  by 
the  routine.  Otherwise,  if  Zi  ^  0  then  RERR(»)  =  the  estimated  maximum  relative  error 

Of  Zi. 

Error  Return.  IERR  =  1  when  n  <  I  and  IERR  =  2  when  an  =  0.  In  these  cases  no 
computation  is  performed. 

Programming.  RBND  employs  the  functions  CPABS  and  SPMPAR.  RBND  was  written 
by  Carl  B.  Bailey  and  modified  by  William  R.  Gavin  (Sandia  Laboratories).  The  format  of 
the  routine  was  modified  by  A.H.  Morris. 
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COPYING  VECTORS 


A  copy  of  a  vector  X  —  (xi,  .  ..,zn)  can  be  made  and  stored  in  the  array  Y  by  the 
following  subroutines: 

CALL  SCOP  Y(n,  X,  kx,  Y,  ky) 

CALL  DCOP  Y(n,  X,  kx,  Y,  ky) 

CALL  CCO  P  Y(n,  X,  kx,  Y,  ky) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  xt-  is  stored  in  X(l+(»  —  l)Jfcx)  for 
*  =  1>  Otherwise,  if  kx  <  0  then  it  is  assumed  that  z$-  is  stored  in  X(1  +  (n  -  t')|A:x|). 

Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y. 

SCOPY  is  used  if  X  and  Y  are  real  arrays,  DCOPY  is  used  if  X  and  Y  are  double 
precision  arrays,  and  CCOPY  is  used  if  X  and  Y  are  complex  arrays.  When  any  of  these 
routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates.  Otherwise,  if  n  >  1 
then  the  components  x,-  of  X  are  stored  in  Y  according  to  the  spacing  specified  by  the  ky 
parameter. 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Sasic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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INTERCHANGING  VECTORS 


The  components  of  two  vectors  X  =  (xi,  . ... ,  xn)  and  Y  =  (yi,  . . .  ,yn)  can  be  inter¬ 
changed  by  the  following  subroutines: 

CALL  SSWAP(n,  X,  kx,Y,  ky) 

CALL  DSWA P(n,X,kx,Y,ky) 

CALL  CSWAP(n,  X,  kx,  Y,  ky) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  i,-  is  stored  in  X(l+(t  - 1)  Ara:)  for 
*  =  1,  . . . ,  n.  Otherwise,  if  kx  <  0  then  it  is  assumed  that  a:,-  is  stored  in  X(1  +  (n  —  i)|fcz|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y . 

SSWAP  is  used  if  X  and  Y  are  real  arrays,  DSWAP  is  used  if  X  and  Y  are  double 
precision  arrays,  and  CSWAP  is  used  if  X  and  Y  are  complex  arrays.  When  any  of  these 
routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates.  Otherwise,  if  n  >  1 
then  the  components  Xi  and  y»  are  interchanged  for  i  =  1,  . ..,n.  Thus,  when  the  routine 
terminates  X  =  (yi ,  . . . ,  yn)  and  Y  =  (si ,  . . . ,  xn). 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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PLANAR  ROTATION  OF  VECTORS 


Let  X  =  (zi,  . . . ,  xn)  and  Y  =  (yi, . . . ,  yn)  be  vectors  and  c  and  s  be  real  numbers 
such  that  c2  +  s2  =  1.  X  and  Y  can  be  replaced  with  cX  +  sV  and  —  sX  +  cY  by  the 
following  subroutines: 

CALL  SROT (n,  X,  kx,  Y,  ky,  c,  s) 

CALL  DROT (n,  X,  kx,  Y,  ky,  c,  s) 

CALL  CSROJ{n,X,kx,Y,ky,c,s) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  X{  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  z*  is  stored  in  X(l  +  (i  —  l)Jfcx)  for 
»  =  1,  . . . ,  n.  Otherwise,  if  kx  <  0  then  it  is  assumed  that  x,-  is  stored  in  X(l  +  (n  —  t)|fcx|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y. 

SROT  is  used  if  X  and  Y  Eire  real  arrays,  DROT  is  used  if  X  and  Y  are  double  precision 
arrays,  and  CSROT  is  used  if  X  and  Y  are  complex  arrays.  The  arguments  c  and  s  are 
real  numbers  when  SROT  and  CSROT  are  used,  and  are  double  precision  numbers  when 
DROT  is  used.  When  any  of  these  routines  is  called,  if  n  <  0  then  the  routine  immediately 
terminates.  Otherwise,  if  n  >  1  then  the  components  x»  and  j a  are  replaced  with  cxi  +  sy» 
and  —  sxi  +  cy*  for  i  —  1,  . . . ,  n. 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Haste  Xtnear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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DOT  PRODUCTS  OF  VECTORS 


The  following  functions  axe  available  for  computing  the  sums  J2i  xiV*  and  ]T\  j c»y,- 
where  X  =  {x\,  . . . ,  xn)  and  Y  =  (1/1,  ,  yn)  are  real  or  complex  vectors. 

SDOT(n,  X,  kx,Y,  ky) 

DDOT(n,  X,  kx,  Y,  ky) 

CDOTC(n,X,  kx,Y,ky) 

CDOTU(n, X,  kx,  Y,  ky) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  x,  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  x<  is  stored  in  X(l  +  (t  —  l)kx)  for 
i  =  1,  . . . ,  n.  Otherwise,  if  kx  <  0  then  it  is  assumed  that  x,-  is  stored  in  X (1  +  (n-OIM). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y. 

SDOT  is  used  if  X  and  Y  are  real  arrays,  and  DDOT  is  used  if  X  and  Y  are  double 
precision  arrays.  SDOT  is  a  real  function  and  DDOT  is  a  double  precision  function.  When 
either  of  these  two  functions  is  called,  if  n  <  0  then  the  function  is  assigned  the  value  0. 

n 

Otherwise,  if  n  >  1  then  the  function  is  assigned  the  value  x*Vi- 

i—1 

CDOTC  and  CDOTU  are  used  if  X  and  Y  are  complex  arrays.  CDOTC  and  CDOTU 
are  complex  functions.  When  either  of  these  two  functions  is  called,  if  n  <  0  then  the  func¬ 
tion  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  CDOTC(n,  X,  kx,  Y,  ky)  is  assigned 

n  n 

the  value  x,jk  and  CDOTU  (n,  X,  kx,Y,ky)  is  assigned  the  value  J2  xiVi- 

»=i  i=i 

Remark.  DDOT  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECI¬ 
SION,  and  CDOTC  and  CDOTV  must  be  declared  to  be  of  type  COMPLEX. 

Programming.  These  functions  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
functions  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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SCALING  VECTORS 


If  a  is  a  real  or  complex  number  and  X  =  (zi,  . . . ,  x„)  a  vector,  then  the  vector  X  can 
be  replaced  with  the  vector  aX  by  the  following  subroutines: 

CALL  SSCAL(n,  a,  X,  kx) 

CALL  DSCAL (n,a,X,kx) 

CALL  CSCAL(n,  a, X,  kx) 

CALL  CSSCAL(n,  a,  X,  kx) 

The  argument  kx  is  a  positive  integer.  It  is  assumed  that  the  component  Xi  is  stored 
in  X(1  +  (j  —  l)A:x)  for  i  =  1, _ ,  n. 

SSCAL  is  used  if  a  is  a  real  number  and  X  a  real  array,  DSCAL  is  used  if  a  is  a  double 
precision  number  and  X  a  double  precision  array,  CSCAL  is  used  if  o  is  a  complex  number 
and  X  a  complex  array,  and  CSSCAL  is  used  if  a  is  a  real  number  and  X  a  complex  array. 
When  any  of  these  routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates. 
Otherwise,  if  n  >  1  then  each  x,-  is  replaced  with  ax*.  Thus  when  the  routine  terminates 
X  =  (ax i,  ... . ,  axn). 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basie  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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VECTOR  ADDITION 


If  a  is  a  real  or  complex  number  and  X  =  (xi,  .  ..,x„)  a  vector,  then  any  vector 

V  —  (yi>  •••,!/«)  can  be  replaced  with  the  vector  aX  +  Y  by  the  following  subroutines: 

CALL  SAXP  Y(n,  a,  X,  kx,  Y,  ky) 

CALL  DAXP  Y(n,  a,  X,  kx,  Y,  ky) 

CALL  CAXP Y(n,  a,  X,  kx,  Y,  ky) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  X*  is  stored  in  X(l+(«  —  l)jfex)  for 
*  =  1,  . . . ,  n.  Otherwise,  if  kx  <  0  then  it  is  assumed  that  xt-  is  stored  in  X (1  +  (n  -  t')|Jfcx|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  the  vector  Y. 

SAXPY  is  used  if  a  is  a  real  number  and  X,  Y  are  real  arrays,  DAXPY  is  used  if  a 
is  a  double  precision  number  and  X,  Y  are  double  precision  arrays,  and  CAXPY  is  used 
if  a  is  a  complex  number  and  X ,  Y  are  complex  arrays.  When  any  of  these  routines  is 
called,  if  n  <  0  or  a  =  0  then  the  routine  immediately  terminates.  Otherwise,  if  n  >  1 
then  y,  is  replaced  with  ax,-  +  y{  for  t  =  1,  ...,n.  Thus  when  the  routine  terminates 

Y  =  (axi  +  yi,  . . . ,  axn  +  yn). 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basie  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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Li  NORM  OF  A  VECTOR 


The  following  functions  axe  available  for  computing  the  L\  norm  of  a  real  vector  or  a 
modified  L\  norm  of  a  complex  vector. 

SASUM(n,  X,  kx) 

OASUM{n,X,kx) 

SCASUM(n,X,A:x) 

X  =  (®i,  . . . ,  xn)  is  a  vector  and  kx  a  positive  integer.  It  is  assumed  that  x»  is  stored 
in  X(1  +  (t  -  l)A:x)  for  »  =  1,  . . . ,  n. 

SASUM  is  used  if  X  is  a  real  array  and  DASUM  is  used  if  A  is  a  double  precision 
array.  SASUM  is  a  real  function  and  DASUM  a  double  precision  function.  When  either  of 
these  functions  is  called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if 

n  >  1  then  the  function  is  assigned  the  value  J2  [x,  |. 

«=i 

SCASUM  is  used  if  X  is  a  complex  array.  SCASUM  is  a  real  function.  When  SCASUM 
is  called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then 

SCASUM(n,  X,  kx)  is  assigned  the  value  ]T)  [|Re(x,-)[  +  |Im(ar*)|]. 

»=i 

Remarks. 

(1)  DASUM  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

(2)  SCASUM(n,X, kx)  is  the  norm  of  the  complex  vector  X  =  (xls  ...,x„)  when  X  is 
regarded  as  a  real  vector  of  dimension  2n.  This  norm  is  frequently  preferred  over  the 

n 

standard  L\  norm  |xt-j  since  it  takes  less  time  to  compute. 

»=i 

Programming.  These  functions  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  P.  T.  Krogh.  The 
functions  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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l2  norm  of  a  vector 


The  following  functions  are  available  for  computing  the  L%  norm  of  a  real  or  complex 
vector. 


SNRM2(n,  X,  kx) 

DNRM2  (n,X,kx) 

SCNRM2(n,  X,  kx) 

X  =  (xi,  . . . ,  xn)  is  a  vector  and  kx  a  positive  integer.  It  is  assumed  that  x,-  is  stored 
in  X(1  +  (t  —  l)fcx)  for  t  =  1,  . . .  ,n. 


SNRM2  is  used  if  X  is  a  real  array,  DNRM2  is  used  if  X  is  a  double  precision  array, 
and  SCNRM2  is  used  if  X  is  a  complex  array.  SNRM2  and  SCNRM2  are  real  functions 
and  DNRM2  a  double  precision  function.  When  any  of  these  functions  is  called,  if  n  <  0 

then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  the  function  is  assigned 

' 


the  value 


E 

.i=i 


Xi\ 


Remark.  The  function  DNRM2  must  be  declared  in  the  calling  program  to  be  of  type 
DOUBLE  PRECISION. 


Programming.  These  functions  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
functions  were  written  by  Charles  Lawson  (Jet  Propulsion  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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Loo  NORM  OF  A  VECTOR 


The  following  functions  are  available  for  finding  the  largest  component  x<  of  a  vector 

X  —  (^1  j  ■  •  •  ,  ®n)  • 

ISAMAX(n,  X,  kx) 

JDAMA  X[n,X,kx) 

ICAMAXfn,  X,  kx) 

The  argument  kx  is  a  positive  integer.  It  is  assumed  that  the  component  x*  is  stored 
in  X(1  +  (»  —  l)fcx)  for  *  =  1,  ,  n. 

ISAMAX  is  used  if  X  is  a  real  array  and  IDAMAX  is  used  if  X  is  a  double  precision 
array.  ISAMAX  and  IDAMAX  are  integer  functions.  When  either  of  these  functions  is 
called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  the 
function  is  assigned  the  value  i  where  i  is  the  smallest  index  such  that  |x»|  =  max{|xy|  :  j  = 
1,  ...,n}. 

ICAMAX  is  also  an  integer  function.  It  is  used  when  X  is  a  complex  array.  K 
n  <  0  then  ICAMAX(n,  X,  kx)  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  the 
function  is  assigned  the  value  i  where  i  is  the  smallest  index  such  that  |Re(xi)j  +  |Im(ii)| 
=  max{|Re(xy)|  +  |Im(xy)|  :j  =  l,  ...,n}. 

Note.  The  mapping  X  -»  max{|Re(xy)|  +  |Im(xy)|  :  j  =  1,  . ..  ,n}  is  the  Loo  norm  of  the 
complex  vector  X  =  (ii,  . . .  ,x„)  when  X  is  regarded  as  a  real  n  X  2  matrix.  This  norm  is 
frequently  preferred  over  the  standard  Loo  norm  max{|xy|  :  j  =  1,  . . . ,  n}  since  it  takes  less 
time  to  compute. 

Programming.  These  functions  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
functions  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  Basic  Linear 
Algebra  Subprograms  for  FORTRAN  Usage.  Report  SAND  77-0898,  Sandia  Laboratories, 
Albuquerque,  New  Mexico,  1977. 
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PACKING  AND  UNPACKING  SYMMETRIC  MATRICES 

An  n  x  n  symmetric  matrix  A  =  (a,y)  can  be  represented  by  either  its  lower  triangular 
elements 

^  all  <*12  a13  •  •  •  ^ 

<*21  <*22  <*23 

<*31  <*32  <*33  •  ■  • 

Vi:! 

or  its  upper  triangular  elements.  If  the  lower  triangular  elements  are  used,  then  the 
packed  form  for  the  matrix  is  an  array  of  dimension  n(n  ~j"  l)/2  containing  the  elements 
<*n<*2i<*22<*3i<*32<*33 '  * •  Similarly,  if  the  upper  triangular  elements  are  used  then  the  packed 
form  for  the  matrix  is  an  array  containing  <*n<*i2  *<*in<*22<*23  ••  •  <*2r»  *  *  ■  Currently  the 

lower  triangular  elements  are  used  for  packing  symmetric  matrices.  The  following 
subroutines  are  available  for  packing  and  unpacking  real  symmetric  matrices. 

CALL  MCVFS(A,  ka,  n,  B) 

CALL  DMCVFS(A,  ka,n,  B) 

A  is  an  n  X  n  symmetric  matrix  and  B  an  array  whose  dimension  is  equal  to  or  greater 
than  n(n  +  l)/2.  The  routines  store  the  packed  form  of  A  in  B.  MCVFS  is  used  if  A  and 
B  are  real  arrays  and  DMCVFS  is  used  if  A  and  B  are  double  precision  arrays.  The  input 
argument  ka  has  the  following  value: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  n. 

Note.  A  and  B  may  begin  in  the  same  location. 

Programmer.  A.  H.  Morris 

CALL  MCVSF(A,  ka,  n,  B) 

CALL  DMCVSF(A,  ka,n,B) 

B  is  an  array  containing  the  elements  of  a  packed  n  x  n  symmetric  matrix  and  A  is  an 
array  of  dimension  ka  X  n  where  ka  >  n.  The  routines  unpack  B  and  store  the  results  in 
A.  MCVSF  is  used  if  A  and  B  are  real  arrays  and  DMCVSF  is  used  if  A  and  B  are  double 
precision  arrays. 

Note.  A  and  B  may  begin  in  the  same  location. 

Programmer.  A.  H.  Morris 
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CONVERSION  OF  REAL  MATRICES 
TO  AND  FROM  DOUBLE  PRECISION  FORM 


The  subroutines  MCVRD  and  MCVDR  are  available  for  converting  real  matrices  to 
and  from  double  precision  form. 

CALL  MCVRD(m,  n,  A,  ka,B,kb) 

A  is  a  real  mxn  matrix  and  B  a  double  precision  2-dimensional  array.  MCVRD  stores 
the  matrix  in  double  precision  form  in  the  array  B.  The  input  arguments  ka  and  kb  have 
the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 

CALL  MCVDR(m,  n,  A,ka,  B,kb) 

A  is  a  double  precision  mxn  matrix  and  B  a  real  2-dimensional  array.  MCVDR  stores 
the  matrix  in  single  precision  form  in  the  array  B.  The  input  arguments  ka  and  kb  have 
the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka>  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 
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STORAGE  OF  REAL  MATRICES  IN  THE  COMPLEX  MATRIX  FORMAT 

The  following  subroutine  is  available  for  storing  a  real  matrix  A  in  the  complex  matrix 
format. 

CALL  MCVRC(m,n,  A,  ka,3,  kb) 

A  is  a  real  m  X  n  matrix  and  B  a,  complex  2-dimensional  array.  MCVRC  stores  the 
matrix  in  complex  form  in  the  array  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka>  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns 

Programmer.  A.  H.  Morris 
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THE  REAL  AND  IMAGINARY  PARTS  OF  A  COMPLEX  MATRIX 


If  A  =  (aij)  is  a  complex  matrix  then  let  Re(A)  =  (Re  (a,-.,)}  and  Im(A)  =  (Im(oi3)) 
denote  the  reed  and  imaginary  parts  of  A.  The  following  subroutines  are  available  for 
obtaining  Re  (A)  and  Im(A). 

CALL  CM  REAL(m,  n,  A,  ka,  B,  kb) 

A  is  a  complex  m  x  n  matrix  and  B  a  real  2-dimensional  array.  CMREAL  obtains 
Re(A)  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 

CALL  CMIMAG(m,n,  A, ka,  B,  kb) 

A  is  a  complex  m  x  n  matrix  and  B  a  real  2-dimensional  array.  CM3MAG  obtains 
Im(A)  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 
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COPYING  MATRICES 


The  following  subroutines  are  available  for  copying  matrices. 

CALL  MCOPY(m,  n,  A,ka,  B,  kb) 

A  is  a  real  mxn  matrix  and  B  a  real  2-dimensional  array.  MCOPY  makes  a  copy  of 
the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka>  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns 

Programmer.  A.  H.  Morris 

CALL  SMCOPY(n,  A,  B) 

A  is  a  real  packed  »xit  symmetric  matrix  and  B  a  real  array  whose  dimension  is  equal 
to  or  greater  than  n(n  +  l)/2.  SMCOPY  makes  a  copy  of  the  packed  symmetric  matrix  A 
and  stores  it  in  B. 

Programmer.  A.  H.  Morris 

CALL  DMCOPY(m,  n,  A,  £6) 

A  is  a  double  precision  m  x  n  matrix  and  B  a  double  precision  2-dimensional  array. 
DMCOPY  makes  a  copy  of  the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and 
kb  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka>  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns 

Programmer.  A.  H.  Morris 

CALL  CMCOPY(m,n,  A,  ka,  B,  kb) 

A  is  a  complex  m  x  n  matrix  and  B  a  complex  2-dimensional  array.  CMCOPY  makes  a 
copy  of  the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka>  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 
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COMPUTATION  OF  THE  CONJUGATE  OF  A  COMPLEX  MATRIX 


If  A  =  (oy)  is  a  complex  matrix  then  let  A  —  (a,y)  denote  the  conjugate  of  A.  The 
following  subroutine  is  available  for  computing  the  conjugate  matrix  A. 

CALL  CMCONJ(m,n,A,  fca,  B,kb) 

_  A  is  a  complex  m  x  n  matrix  and  B  a  complex  2-dimensional  array.  CMCONJ  computes 
A  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Remark.  A  and  B  may  reference  the  same  storage  area  when  ka  =  kb. 

Programmer.  A.  H.  Morris 
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TRANSPOSING  MATRICES 


The  subroutines  TPOSE,  DTPOSE,  CTPOSE  and  TIP,  DTIP,  CTIP  are  available  for 
transposing  a  matrix  A.  TPOSE,  DTPOSE,  and  CTPOSE  are  used  if  the  results  are  to  be 
stored  in  a  separate  storage  area  B.  TIP,  DTIP,  and  CTIP  are  used  if  the  results  are  to  be 
stored  in  A  (i.e.,  if  the  transposition  is  to  be  done  in  place). 

CALL  TPOSE(m,n,A,fca,  B,kb) 

CALL  DTPOSE(m,  n.  A,  ka,  B,  fci) 

CALL  CTPOSE(m,n,  A,  lea,  B,  kb) 

TPOSE  is  called  if  A  is  a  real  matrix  and  B  a  real  array,  DTPOSE  is  called  if  A  is  a 
double  precision  matrix  and  B  a  double  precision  array,  and  CTPOSE  is  called  if  A  is  a 
complex  matrix  and  B  a  complex  array. 

A  is  a  matrix  having  m  rows  and  n  columns,  and  B  a  2-dimensional  arrary.  The  routine 
transposes  A  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  n,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris 

CALL  TIP(A,  m,  n,  MOVE,  k,  MDIM) 

CALL  DTIP(A,  m,  n,  MOVE,  k,  MDIM) 

CALL  CTIP(A,m,n,MOVE,ifc,MDIM) 

TIP  is  called  if  A  is  a  real  array,  DTIP  is  called  if  A  is  a  double  precision  array,  and 
CTIP  is  called  if  A  is  a  complex  array. 

A  is  an  array  of  dimension  mn  which  contains  anmxti  matrix  to  be  transposed.  The 
routine  transposes  the  matrix  and  stores  the  results  in  A.  If  m  =  n  then  the  arguments 
MOVE,  k,  MDEM  are  ignored. 

If  m  ^  n  then  k  may  be  any  integer.  If  k  <  0  then  MOVE  is  ignored.  Otherwise,  if 
k  >  1  then  MOVE  is  assumed  to  be  an  array  of  dimension  k.  MOVE  is  a  storage  area  for 
saving  information  that  may  help  speed  up  the  transposition  process.  If  no  information  is 
saved  then  TIP,  DTIP,  and  CTIP  may  run  2-10  times  slower  than  TPOSE,  DTPOSE,  and 
CTPOSE.  However,  the  use  of  a  storage  area  may  or  may  not  actually  speed  up  the  trans¬ 
position  process.  This  depends  entirely  on  the  values  of  m  and  n.  MDIM  is  a  variable  that 
is  set  by  the  routine.  After  the  routine  terminates,  MDIM  will  be  the  estimated  optimum 
setting  for  k  for  the  current  values  of  m  and  n. 

Programming.  The  routines  TIP,  DTIP,  and  CTIP  employ  the  subroutine  INFCTR. 
The  routines  were  written  by  Norman  Brenner  (Dept,  of  Earth  and  Planetary  Sciences, 
Massachusetts  Institute  of  Technology),  and  modified  by  A.  H.  Morris. 
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Reference.  Brenner,  Norman,  “Algorithm  467.  Matrix  Transposition  in  Place,”  Comm. 
ACM  16  (1973),  pp.  692-694. 
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COMPUTING  ADJOINTS  OF  COMPLEX  MATRICES 


If  A  —  (a*j)  then  let  A*  —  (ay,-)  denote  the  adjoint  of  A.  The  following  subroutines  are 
available  for  computing  A* . 

CALL  CMADJ(m,  n,  A,  ka,B,  kb) 

A  is  a  complex  m  X  n  matrix  and  B  a  complex  2-dimensional  array.  CMADJ  computes 
A*  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  n,  and  that  B  contains  at  least  n  columns. 

Remark.  CMADJ  combines  the  following  operations: 

CALL  CTPOSE(m,  n,  A,  ka,  B,  kb) 

CALL  CMCONJ(n,  m,  B,  kb,  B,  kb) 

It  is  assumed  that  A  and  B  are  different  storage  areas. 

Programmer.  A.  H.  Morris 

CALL  CTRANS(Jfca,n,A) 

A  is  a  complex  array  of  dimension  ka  xn  which  contains  annxti  matrix.  CTRANS 
computes  the  adjoint  of  the  matrix  and  stores  the  results  in  A.  It  is  assumed  that  ka  >  n. 

Programmer.  George  J.  Davis  (Georgia  State  University) 
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MATRIX  ADDITION 


The  matrix  sum  C  =  A  +  B  can  be  computed  by  the  following  subroutines: 

CALL  MADD(m,n,  A,ka,  B,kb,C,kc) 

A  and  B  are  real  m  x  n  matrices  and  C  a  real  2-dimensional  array.  MADD  computes 
A+  B  and  stores  the  results  in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n.  columns 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  =  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris" 

CALL  SMADD(n,  A,  B, C) 

A  and  B  are  real  packed  nxn  symmetric  matrices  and  C  is  a  reed  array  whose  dimension 
is  equal  to  or  greater  than  n(n  + 1)/2.  SMADD  computes  A-j-  B,  which  is  also  a  symmetric 
matrix,  and  stores  the  results  in  packed  form  in  C. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  the  result  C  will  overwrite  the  input  data  A.  Similarly,  B  will  be  overwritten  if 
C  begins  in  the  same  location  as  B.  Otherwise,  if  C  does  not  begin  in  the  same  location 
as  A  or  B,  then  it  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage 
areas  for  A  and  B. 

Programmer.  A.  H.  Morris 

CALL  DMADD(m,n,  A,  ka,B,kb,C,kc) 

A  and  B  are  double  precision  m  x  n  matrices  and  C  a  double  precision  2-dimensional 
array.  DMADD  computes  A  +  B  and  stores  the  results  in  C.  The  arguments  ka,  kb,  kc 
have  the  following  values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 
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The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  —  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris 

CALL  C M AD  D  (m,  n,  A,  ka,  B,  kb,  C,  kc) 

A  and  B  are  complex  m  x  n  matrices  and  C  a  complex  2-dimensional  array.  CMADD 
computes  A+  B  and  stores  the  results  in  C.  The  arguments  ka,  kb,  kc  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  —  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris 
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MATRIX  SUBTRACTION 


The  matrix  difference  C  =  A  —  B  can  be  computed  by  the  following  subroutines: 
CALL  MSUBT(m,n,  A,ka,  B,  kb,C,kc) 

A  and  B  are  real  m  X  n  matrices  and  C  a  real  2-dimensional  array.  MSUBT  computes 
A—  B  and  stores  the  results  in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  =  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris” 

CALL  SMSUBT(n,A,£,C) 

A  and  B  are  real  packed  nxn  symmetric  matrices  and  C  is  a  real  array  whose  dimension 
is  equal  to  or  greater  than  n(n  + 1)/2.  SMSUBT  computes  A— B,  which  is  also  a  symmetric 
matrix,  and  stores  the  results  in  packed  form  in  C. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  the  result  C  will  overwrite  the  input  data  A.  Similarly,  B  will  be  overwritten  if 
C  begins  in  the  same  location  as  B.  Otherwise,  if  C  does  not  begin  in  the  same  location 
as  A  or  B,  then  it  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage 
areas  for  A  and  B. 

Programmer.  A.  H.  Morris 

CALL  DMSUBT(m,n,  A,A:a,  B,kb,C,  kc) 

A  and  B  are  double  precision  m  X  n  matrices  and  C  a  double  precision  2-dimensional 
array.  DMSUBT  computes  A  —  B  and  stores  the  results  in  C.  The  arguments  ka,  kb,  kc 
have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 
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The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  =  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris 

CALL  CMSUBT(m,n,  A,  ka,  B,kb,C,  kc) 

A  and  B  are  Complex  m  x  n  matrices  and  C  a  complex  2-dimensional  array.  CMSUBT 
computes  A  -  B  and  stores  the  results  in  C.  The  input  arguments  ka,  kb,  kc  have  the 
following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  —  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  has  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  =  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then.it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris 
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MATRIX  MULTIPLICATION 


The  matrix  product  C  —  AB  may  be  computed  by  the  subroutines  MTMS,  DMTMS, 
CMTMS  or  MPROD,  DMPROD,  CMPROD.  MTMS,  DMTMS,  and  CMTMS  can  be  used 
if  the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  Otherwise, 
if  the  components  of  C  are  to  be  stored  in  the  storage  area  for  A  or  B,  then  MPROD, 
DMPROD,  or  CMPROD  must  be  used. 

CALL  MTMS(m,  n,  £,  A,  ka,  B,  kb,  C,  kc ) 

CALL  DMTMS(m,  n,  £,  A,  ka,  B,  kb,  C,  kc) 

CALL  CMTMS(m,  n,  £,  A,  ka,  B,  kb,  C,  kc) 

MTMS  is  used  if  A  and  B  are  real  matrices  and  C  a  real  array,  DMTMS  is  used  if  A 
and  B  are  double  precision  matrices  and  C  a  double  precision  array,  and  CMTMS  is  used 
if  A  and  B  are  complex  matrices  and  C  a  complex  array. 

A  is  a  matrix  having  m  rows  and  n  columns,  B  a  matrix  having  n  rows  and  £  columns, 
and  C  a  2-dimensional  array.  The  routine  computes  the  product  AB  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  n,  kc  >  m,  and  that  C  contains  at  least  £  columns. 

Remark.  It  is  assumed  that  the  storage  area  for  C  is  separate  from  the  storage  areas  for  A 
and  B. 

Programmer.  A.  H.  Morris 

CALL  MPROD(m,  n,  £,  A,  ifca,  B,  kb, C,  Jbc,WK) 

CALL  DMPROD(m,n,£,A,fca,B,H,C,fcc,WK) 

CALL  CMPROD(m,  n, £,  A, ka,  B,  kb,  C,  kc, WK) 

MPROD  is  used  if  A  and  B  are  real  matrices  and  C  and  WK  are  real  arrays,  DMPROD 
is  used  if  A  and  B  are  double  precision  matrices  and  C  and  WK  are  double  precision  arrays, 
and  CMPROD  is  used  if  A  and  B  are  complex  matrices  and  C  and  WK  are  complex  arrays. 

A  is  a  matrix  having  m  rows  and  n  columns,  B  a  matrix  having  n  rows  and  £  columns, 
and  C  a  2-dimensional  array.  The  routine  computes  the  product  AB  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  n,  kc  >  m,  and  that  C  contains  at  least  £  columns. 
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WK  is  an  array  that  serves  as  a  temporary  storage  area.  The  matrix  C  may  begin  in 
the  same  location  as  A  or  B.  If  C  begins  in  the  same  location  as  A,  then  it  is  assumed 
that  kc  =  ka  and  that  the  dimension  of  WK  is  equal  to  or  greater  than  l.  In  this  case,  the 
result  C  will  overwrite  the  input  data  A.  Similarly,  if  C  begins  in  the  same  location  as  B 
then  it  is  assumed  that  kc  =  kb  and  that  the  dimension  of  WK  is  equal  to  or  greater  than 
m.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that 
the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case, 
the  array  WK  is  not  referenced. 

Remark.  If  C  begins  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the  storage 
areas  for  A  and  B  are  distinct  storage  areas. 

Programming.  MPROD  employs  the  subroutines  RLOC  and  YCHG,  DMPROD  employs 
the  subroutines  DLOC  and  DYCHG,  and  CMPROD  employs  the  subroutines  CLOC  and 
CYCHG.  The  routines  were  written  by  A.  H.  Morris. 
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PRODUCT  OF  A  PACKED  SYMMETRIC  MATRIX  AND  A  VECTOR 


Let  A  denote  a  packed  symmetric  matrix  of  order  n  and  x  a  column  vector  of  dimension 
n  where  n  >  1.  Then  the  following  subroutines  are  available  for  computing  the  product  Ax. 

CALL  SVPRD(A,n,x,  y) 

CALL  DSVPRD(A,n,x,y) 

The  argument  y  is  an  array  of  dimension  n.  SVPRD  is  called  when  A,x,y  are  real 
arrays  and  DSVPRD  is  called  when  A,x,  y  are  double  precision  arrays.  When  either  of 
these  routines  is  called,  Ax  is  computed  and  stored  in  y. 

Programmer.  A.  H.  Morris 
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TRANSPOSE  MATRIX  PRODUCTS 


If  A4  denotes  the  transpose  of  A,  then  the  matrix  product  C  =  AtB  can  be  computed 
by  the  following  subroutine: 

CALL  TMPROD(m,  n,i,  A,  ka,B,kb,C,kc ) 

A  is  a  real  matrix  having  m  rows  and  n  columns,  B  a  real  matrix  having  m  rows  and  l 
columns,  and  C  a  real  2-dimensional  array.  TMPROD  computes  AiB  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
Here  it  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  n,  and  that  C  contains  at  least  t  columns 
Also  it  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for 
A  and  B. 

Note.  All  inner  products  ^  akibkj  are  computed  in  double  precision  and  the  results  stored 

fc 

in  single  precision. 

Programmer.  A.  H.  Morris 
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SYMMETRIC  MATRIX  PRODUCTS 


If  A4  denotes  the  transpose  of  A,  then  the  matrix  product  AtA  can  be  computed  and 
its  packed  form  stored  in  the  array  B  by  the  following  subroutine: 

CALL  SMPROD(m,  n,  A,  ka, B) 

A  is  a  real  m  x  n  matrix  and  B  a  real  array  whose  dimension  is  equal  to  or  greater 
than  n(n  +  l)/2.  SMPROD  computes  A4 A  and  stores  its  packed  form  in  B.  The  input 
argument  ka  has  the  following  value: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  m. 

Note.  All  inner  products  J2.aki&kj  are  computed  in  double  precision  and  the  results  stored 

k 

in  single  precision. 

Programmer.  A.  H.  Morris 
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KRONECKER  PRODUCT  OF  MATRICES 


If  A  is  an  m  x  n  matrix  and  B  a  k  x  £  matrix,  then  the  Kronecker  product  A  ®  B  is 
defined  by 

ail  B  ainB 


A®  B  = 


■  a  ml  -5 


nB  j 


From  this  definition  we  obtain: 

(1)  (Transpose  Equality)  (A  ®  B)4  =  A4  ®  B*. 

(2)  (A  ®  B)  ®  E  =  A  ®  (B  <8>  E)  for  any  matrix  E. 

(3)  (A®  B)(C  ®  D)  —  (AC)  ®  (BB)  if  C  is  a  matrix  having  n  rows  and  D  a  matrix  having 
£  rows. 

If  A  and  B  are  complex  square  matrices  of  orders  m  and  k  respectively,  then  from  the  Jordan 
canonical  forms  of  A  and  B  the  determinant  equality  det  (A®  5)  =  (det  A)*  (det  B)m  can 
be  verified.  Moreover,  if  A  and  B  are  nonsingular  then  (A®  B)-1  =  A-1  ®  B_1  from  (3). 


The  following  subroutines  are  available  for  computing  C  =  A®  B. 

CALL  KPROD(A,  ka,  m,  n,  B,  kb,  k, t, C,  kc) 

CALL  DKPROD(A,  ka,  m,n,B,  kb,  k,i,C,  kc) 

CALL  CKPROD(A,  ka,m,n,  B,kb,k,£,C,kc) 


It  is  assumed  that  A  is  an  m  x  n  matrix,  B  a  k  x  t  matrix,  and  C  a  2-dimensional 
array.  KPROD  is  used  if  A,B,C  are  real  arrays,  DKPROD  is  used  if  A,B,C  are  double 
precision  arrays,  and  CKPROD  is  used  if  A,  B,C  are  complex  arrays.  When  the  routine  is 
called,  A  ®  B  is  computed  and  stored  in  C. 

The  arguments  ka,  kb,  and  kc  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  assumed  that  ka  >  m,  kb  >  k,  kc  >  mk,  and  that  C  contains  at  least  n£  columns. 

Remark.  It  is  assumed  that  the  array  C  does  not  overlap  with  A  or  B. 

Programmer.  A.  H.  Morris 
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INVERTING  GENERAL  REAL  MATRICES  AND  SOLVING 
GENERAL  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


The  subroutines  CROUT,  KROUT,  MSLV,  NPIVOT,  and  DMSLV  are  available  for 
inverting  real  matrices  A  and  solving  systems  of  real  linear  equations  AX  =  B.  CROUT, 
KROUT,  MSLV,  and  NPIVOT  solve  single  precision  problems,  and  DMSLV  solves  double 
precision  problems. 

All  the  routines  except  NPIVOT  are  general-purpose,  employing  partial  pivot  Gauss 
elimination.  NPIVOT  can  only  occasionally  be  used  since  it  uses  Gauss-Jordan  elimination 
with  no  pivot  search.  Normally,  CROUT  and  KROUT  produce  the  same  results,  which  will 
be  of  equal  or  greater  accuracy  than  the  results  produced  by  MSLV.  However,  since  many 
of  the  calculations  are  performed  in  double  precision  in  CROUT  and  KROUT,  whereas 
only  single  precision  is  used  in  MSLV,  MSLV  may  run  2-3  times  faster  than  CROUT  and 
KROUT. 

CALL  CROUT(MO,  n,  m,  A,  ka,  B,  kb,  D,  INDEX, TEMP) 

A  is  a  real  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  ^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  —  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  the  argument  kb  is  ignored. 

D  is  a  real  variable.  When  CROUT  is  called,  D  is  assigned  the  value  det(A)  where 
det(A)  is  the  determinant  of  A.  If  D  is  found  to  have  the  value  0  then  the  routine  immedi¬ 
ately  terminates. 

INDEX  is  an  array  of  dimension  n  —  1  or  larger  that  is  used  by  the  routine  for  keeping 
track  of  the  row  interchanges  that  are  made.  If  MO  ^  0  then  INDEX  is  ignored. 

TEMP  is  a  real  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine.  If 
MO  ^  0  then  TEMP  is  ignored. 

Remarks. 

(1)  KROUT  should  be  used  instead  of  CROUT  when  the  determinant  D  is  not  needed. 

Underflow  or  overflow  in  the  calculation  of  D  may  cause  CROUT  to  terminate  prema¬ 
turely. 

(2)  The  matrix  A  is  destroyed. 
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Algorithm.  The  Crout  procedure  is  used.  All  inner  products  are  computed  in  double 
precision  and  the  results  returned  in  single  precision.  Partial  pivoting  is  performed. 

Programming.  CROUT  calls  the  subroutine  CROUTO.  These  routines  were  written  by 
A.  H.  Morris. 

CALL  KROUT(MO,n,  m,  A,  ka,  B,  IERR, INDEX, TEMP) 

A  is  a  real  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  7^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  —  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  the  argument  kb  is  ignored. 

INDEX  is  an  array  of  dimension  n  -  1  or  larger  that  is  used  by  the  routine  for  keeping 
track  of  the  row  interchanges  that  are  made.  If  MO  7^  0  then  INDEX  is  ignored. 

TEMP  is  a  real  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine.  If 
MO  7^  0  then  TEMP  is  ignored. 

Error  Return.  IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates  IERR  has  one  of  the  following  values: 

IERR  =  0  The  requested  results  were  obtained. 

IERR  =  -1  Either  n,  ka,  or  kb  is  incorrect.  In  this  case,  A  and  B  have  not 
been  modified. 

IERR  =  k  The  kth  column  of  A  has  been  reduced  to  a  column  containing 
only  zeros. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remark.  The  matrix  A  is  destroyed. 

Algorithm.  The  CROUT  procedure  is  used.  All  inner  products  are  computed  in  double 
precision  and  the  results  returned  in  single  precision.  Partial  pivoting  is  performed. 

Programming.  KROUT  calls  the  subroutine  KROUTO.  These  routines  were  written  by 
A.  H.  Morris. 

CALL  NPIVOT(n,  m,  A,  ka,  B,  kb,  D,  IERR) 

A  is  a  real  matrix  of  order  n  where  n  >  1.  When  NPIVOT  is  called  the  inverse  of  A  is 
computed  and  stored  in  A. 
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The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  =  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  kb  is  ignored. 

D  is  a  real  variable.  On  input  D  must  be  assigned  a  value  by  the  user.  If  the  input 
value  is  r,  then  when  NPIVOT  terminates  D  =  rd  where  d  is  the  determinant  of  A. 

Error  Return.  IERR  is  an  integer  variable.  If  inversion  is  successful  then  IERR  is  assigned 
the  value  0.  Otherwise,  IERR  =  1  if  NPIVOT  cannot  invert  the  matrix. 

Algorithm.  The  Gauss- Jordan  procedure  is  used.  However,  no  pivot  searching  is  done. 
NPIVOT  terminates  (with  IERR  set  to  1)  whenever  a  zero  pivot  element  is  encountered. 

Remarks.  Since  pivot  search  is  frequently  needed  to  invert  a  matrix,  and  since  pivot  search 
is  normally  required  to  obtain  accurate  results,  NPIVOT  should  not  be  used  except  on 
those  occasions  when  pivot  search  is  known  to  be  superfluous. 

Programmer.  A.  H.  Morris 

CALL  MSLV(MO,  n,  m,  A,  ka,  B ,  kb,  D,  RCOND,IERR,IPVT,WK) 

CALL  DMSLV(MO,  n,m,A,  ka,  B,  kb,  D,  RCOND,IERR,IPVT,WK) 

A  is  a  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  ^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  =  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  the  argument  kb  is  ignored. 

D  is  an  array  of  dimension  2.  When  either  routine  is  called  the  determinant  det(A)  of 
the  matrix  A  is  computed.  If  det(A)  =  d  •  10fc  where  1  <  |d[  <  10  and  k  an  integer,  then  d 
is  stored  in  D(l)  and  the  exponent  k  is  stored  in  floating  point  form  in  .0(2). 

RCOND  is  a  variable.  When  either  routine  is  called,  the  routine  makes  an  estimate  c 
of  the  condition  number  of  the  matrix  A  (relative  to  the  L\  norm).  RCOND  is  assigned 
the  value  l/c. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routines  for 
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keeping  track  of  the  row  interchanges  that  are  made.  WK  is  an  array  of  dimension  n  or 
larger  that  is  used  as  a  work  space. 

Remarks. 

(1)  If  MSLV  is  called  then  it  is  assumed  that  A  and  B  are  real  matrices,  D  and  WK  real 
arrays,  and  RCOND  a  real  variable.  Otherwise,  if  DMSLV  is  called  then  it  is  assumed 
that  A  and  B  are  double  precision  matrices,  D  and  WK  double  precision  arrays,  and 
RCOND  a  double  precision  variable. 

(2)  RCOND  satisfies  0  <  RCOND  <  1.  If  RCOND  ps  10-*  then  one  can  expect  the  results 
to  have  approximately  k  fewer  significant  digits  of  accuracy  them  the  elements  of  A. 
For  example,  if  MSLV  is  used  to  invert  a  matrix  in  the  14  digit  CDC  single  precision 
arithmetic  and  RCOND  =  .4E-3,  then  the  computed  coefficients  of  the  inverse  matrix 
should  normally  be  accurate  to  about  11  digits.  In  general,  RCOND  characterizes  how 
well  or  poorly  conditioned  the  problem  is.  If  RCOND  &  1  then  one  should  expect  the 
results  to  be  almost  as  accurate  as  the  original  data  A.  However,  if  RCOND  «  0  then 
one  should  expect  the  results  to  be  nonsense; 

(3)  The  matrix  A  is  destroyed. 

Error  Return.  IERR  is  an  integer  variable.  If  RCOND  is  sufficiently  large  so  that  1  + 
RCOND  >  1,  then  IERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1+RCOND  =  1 
then  IERR  is  set  to  1  and  the  routine  terminates.  In  this  cause,  A  will  have  been  destroyed 
but  B  will  not  have  been  modified.  Also  the  determinant  will  not  have  been  computed. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used. 

Programming.  MSLV  and  DMSLV  are  driver  routines  for  the  LINPACK  subroutines 
SGECO,  SGEFA,  SGESL,  SGEDI  and  DGECO,  DGEFA,  DGESL,  DGEDI.  The  subrou¬ 
tines  were  coded  by  Cleve  Moler  (University  of  New  Mexico).  The  subroutines  employ  the 
vector  routines  SSWAP,  SDOT,  SSCAL,  SAXPY,  SASUM,  ISAMAX  and  DSWAP,  DDOT, 
DSCAL,  DAXPY,  DASUM,  IDAMAX. 

References. 

(1)  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK  Users’ 
Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 
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Condition  Number  of  a  Matrix,”  SIAM  Journal  of  Numerical  Analysis  16  (1979), 
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SOLUTION  OF  REAL  EQUATIONS  WITH  ITERATIVE  IMPROVEMENT 


Given  a  real  nxn  matrix  A  and  column  vector  b.  The  following  subroutine  is  available 
for  solving  the  equation  Ax  =  b.  Iterative  improvement  is  performed  to  compute  the  solution 
x  to  machine  accuracy. 

CALL  SLVMP  (MO, n,  A,  ka,  b,  X,WK,IWK,IND) 

MO  is  an  input  argument  which  specifies  if  SLVMP  is  being  called  for  the  first  time. 
On  an  initial  call,  MO  =  0  and  we  have  the  following  setup: 

A  is  a  2-dimensional  real  array  of  dimension  ka  X  n  containing  the  matrix  A,  b  a  real 
vector  of  dimension  n,  and  X  a  real  array  of  dimension  n.  When  SLVMP  is  called,  Ax  —  b 
is  solved  and  the  solution  stored  in  X.  A  and  b  are  not  modified  by  the  routine. 

WK  is  a  real  array  of  dimension  n^+n  or  larger,  and  IWK  an  integer  array  of  dimension 
n  or  larger.  These  arrays  are  for  internal  use  by  the  routine.  On  an  initial  call  to  SLVMP, 
an  LU  decomposition  is  obtained  for  A  and  stored  in  WK  and  IWK.  Then  the  equation 
Ax  —  b  is  solved. 

IND  is  an  integer  variable  that  reports  the  status  of  the  results.  On  an  initial  call  to 
SLVMP,  when  the  routine  terminates  IND  has  one  of  the  following  values: 

IND  =  0  The  solution  X-was  obtained  to  machine  accuracy. 

IND  =  IX  was  obtained,  but  not  to  machine  accuracy. 

IND  —  —k  The  kth  column  of  A  was  reduced  to  a  column  containing  only 
zeros. 

When  IND  =  —k,  no  solution  is  obtained. 

After  an  initial  call  to  SLVMP,  if  IND  =  0  or  1  on  output,  then  the  routine  may  be 
called  to  solve  a  new  set  of  equations  Ax  =  b  without  having  to  redecompose  the  matrix 
A.  In  this  case,  the  input  argument  MO  may  be  set  to  any  nonzero  value.  When  MO  ^  0 
it  is  assumed  that  only  b  has  been  modified.  The  routine  employs  the  LU  decomposition 
obtained  on  the  initial  call  to  SLVMP  to  solve  the  new  set  of  equations  Ax  =  b.  On  output 
X  will  contain  the  solution  to  the  new  set  of  equations.  As  before,  A  and  b  are  not  modified 
by  the  routine. 

If  SLVMP  is  recalled  with  MO  ^  0,  then  when  the  routine  terminates  IND  has  one  of 
the  following  values: 

IND  —  0  The  solution  X  was  obtained  to  machine  accuracy. 

IND  =  1  X  was  obtained,  but  not  to  machine  accuracy. 

Programming.  SLVMP  calls  the  subroutine  LUIMP.  These  routines  were  written  by  A.  H. 
Morris.  The  subroutines  MCOPY,  SGEFA,  SGESL,  SSCAL,  SAXPY  and  functions  SPM- 
PAR,  SDOT,  ISAMAX  are  also  employed. 
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SOLUTION  OF  ALMOST  BLOCK  DIAGONAL  SYSTEMS 
OF  LINEAR  EQUATIONS 


Consider  a  system  Ax  =  b  of  linear  equations  where  A  is  an  n  x  n  matrix  having  the 
block  structure 


Here  it  is  assumed  that  A,-  is  an  r»  X  c,  matrix  for  *  =  1,  . . . ,  m,  and  that  M  and  A,+i  may 

m 

have  8i  >  0  columns  in  common  for  t  <  m.  Thus.  ^2  r<  =  n  and  block  A*  begins  in  column 

t=i 

»— l 

Z)  (<:*  —  Sk)  +  1  for  i  >  2.  It  is  also  assumed  that  three  successive  blocks  A,_1}  A,-,  A^+i 

k=  1 

do  not  have  columns  in  common.  Thus  <  e<  for  t  =  2,  . . . ,  m  —  1.  If  m  >  2  then 

the  following  subroutines  are  available  for  solving  Ax  —  b. 

CALL  ARC  EC  O  (n,  S  ,MTR,m,I  WK,6,  Jif  ,IND) 

m 

5  is  an  array  of  dimension  Tici  or  larger.  On  input  S  contains  the  blocks  A1}  Am 

«=i 

of  the  matrix  A.  The  blocks  are  stored  in  sequence.  A\  is  stored  in  the  first  r^ci  locations 
of  S,  Aj  is  stored  in  the  next  rjcj  locations,  etc.  For  each  the  columns  of  A,-  are  stored 
in  sequence  in  S. 


Example. 


<*11 

<*12 

<*1S 

0 

0 

\ 

<*21 

<*22 

<*2S 

0 

0 

0 

<*32 

<*3S 

<*34 

0 

0 

<*42 

<*43 

<*44 

0 

0 

0 

0 

0 

<*55 

M 

then  n  =  5,  m  =  3,  Si  =  2,  and  62  =  0.  Also,  S  is  an  array  containing  the  data  an, 021, 

Ol2}«2a,  <*13,023,  <*32,  <*42,  <*33, <*43,  <*34, <*44,  <*55- 


MTR  is  an  integer  matrix  of  dimension  3  x  m  containing  the  block  information  of  the 
matrix  A: 

MTR(1,  *)  =  rt-  (i  =  1,  . . . ,  m) 

MTR(2,*‘)  =  Ci  (*  =  I,  . . .  ,m) 

MTR(3,  *)  =  8i  (t  =  1,  . . . ,  m  —  1) 

For  convenience,  the  routine  sets  MTR(3,  m)  =  0. 
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X  is  an  array  of  dimension  n  or  larger.  When  ARCECO  is  called,  A  is  decomposed  and 
then  the  equations  Ax  =  b  are  solved.  The  decomposition  of  A  is  stored  in  5,  overwriting 
the  initial  input  data  A,  and  the  solution  x  is  stored  in  X.  The  vector  b  is  destroyed  by  the 
routine. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
indices  involved  in  the  decomposition  of  A  are  stored  in  IWK. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  ARCECO  terminates, 
IND  has  one  of  the  following  values: 

IND  =  0  The  system  of  equations  was  solved. 

IND  =  1  (Input  Error)  Either  n,  m,  or  MTR  is  incorrect,  or  three  successive 
blocks  Ai„i,Ai,  Ai+i  of  A  have  columns  in  common. 

IND  =— 1  A  is  a  singular  matrix.  The  equations  cannot  be  solved. 

Usage.  After  a  call  to  ARCECO,  if  IND  =  0  on  output  then  the  subroutine  ARCESL  (see 
below)  may  be  called  to  solve  a  new  set  of  equations  Ax  —  b  without  having  to  redecompose 
the  matrix  A.  ARCESL  employs  the  decomposition  of  A  obtained  by  ARCECO. 

Algorithm.  A  modification  of  the  alternate  row  and  column  elimination  procedure  by  Varah 
is  used. 

Programming.  ARCECO  employs  the  routines  ARCEDC,  ARCEPR,  ARCEPC,  ARCESL, 
ARCEFS,  ARCEFM,  ARCEFE,  ARCEBS,  ARCEBM,  and  ARCEBE.  These  routines  were 
developed  by  J.  C.  Diaz  (Mobil  Research  and  Development  Corp.,  Farmers  Branch,  Texas), 
G.  Fairweather  (University  of  Kentucky),  and  P.  Keast  (University  of  Toronto). 

Reference.  Diaz,  J.  C.,  Fairweather,  G.,  and  Keast,  P.,  “FORTRAN  Packages  for  Solving 
Certain  Almost  Block  Diagonal  Linear  Systems  by  Modified  Alternate  Row  and  Column 
Elimination,”  ACM  Trans.  Math  Software  9  (1983),  pp.  358-375. 

CALL  ARCESL(5,MTR,m,IWK,6,A) 

The  argument  m  is  the  number  of  blocks  A\,  ...,Am  in  the  matrix  A.  ARCESL 
may  be  used  only  when  IND  =  0  on  output  from  ARCECO.  In  this  case,  S  contains 
the  decomposition  of  A  obtained  by  ARCECO  and  IWK  contains  the  pivot  indices  of  the 
decomposition.  The  argument  b  is  a  vector  of  dimension  n,  and  X  an  array  of  dimension 
n  or  larger.  When  ARCESL  is  called,  the  equations  Ax  —  b  are  solved  and  the  solution 
stored  in  X.  The  vector  b  is  destroyed  by  the  routine. 

Programming.  ARCESL  calls  the  subroutines  ARCEFS,  ARCEFM,  ARCEFE,  ARCEBS, 
ARCEBM,  and  ARCEBE.  These  routines  were  developed  by  J.  C.  Diaz  (Mobil  Research 
and  Development  Corp. .Farmers  Branch,  Texas),  G.  Fairweather  (University  of  Kentucky), 
and  P.  Keast  (University  of  Toronto). 
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SOLUTION  OF  ALMOST  BLOCK  TRIDIAGONAL  SYSTEMS 
OF  LINEAR  EQUATIONS 


Consider  a  system  Tx  =  b  of  linear  equations  where  T  is  a  square  matrix  having  the 
block  structure 

Bi  Ct 

A2  B2  Q 

C3  A3  B$ 


Cn-l  An-i  Bn-i 
Bn  Cn  An 

Here  it  is  assumed  that  Ak,Bk,Ck  (k  ■=  1,  . . . ,  n)  are  m  x  m  matrices,  and  that  b  is  a 
column  vector  of  dimension  mn.  If  n  >  4  then  the  following  subroutine  is  available  for 
solving  Tx  =  b. 

CALL  BTSLV(MO,m,  n,  A,  B,  C,  X, IP, IND) 

MO  is  an  input  argument  which  specifies  if  BTSLV  is  being  called  for  the  first  time. 
On  an  initial  call,  MO  =  0  and  we  have  the  following  setup: 

A,  B,  C  are  3-dimensional  arrays  of  dimension  m  x  m  x  n  where  the  (*',j)-th  elements 
of  the  matrices  Ak,Bk,Ck  are  stored  in  A(i,j,k),  B(i,j,k)}  C(i,j,k)  for  k  =  1, 
A,B,C' are  modified  by  the  routine. 

X  is  an  array  of  dimension  mn  or  larger.  On  input,  the  vector  &  is  stored  in  X.  When 
BTSLV  is  called,  if  a  solution  x  is  obtained  for  Tx  =  b  then  the  solution  is  stored  in  X. 

IP  is  an  array  of  dimension  mn  or  larger  that  is  used  by  the  routine  for  listing  the  row 
interchanges  that  are  made. 

On  an  initial  call  to  the  routine,  a  block  LU  decomposition  is  performed  on  T,  the 
results  of  which  are  stored  in  A,  B,C.  This  decomposition  involves  row  interchanges  only 
within  the  diagonal  blocks  At;  i.e.,  no  row  interchanges  are  performed  between  rows  of 
different  blocks  At  and  At.  Thus  it  may  occur  that  the  decomposition  of  a  nonsingular 
matrix  T  cannot  be  completed.  IND  is  a  variable  that  reports  the  status  of  the  results. 
When  BTSLV  terminates,  IND  has  one  of  the  following  values: 

IND  =  0  T  was  decomposed  and  the  equations  Tx  =  b  solved. 

IND  =-l  (Input  Error)  Either  m  <  1  or  n  <  4. 

IND  =  k  The  decomposition  process  failed  in  the  kth  diagonal  block.  The 
routine  cannot  solve  the  equations  in  their  present  form. 

After  an  initial  call  to  BTSLV,  if  IND  =  0  then  the  routine  may  be  recalled  with  MO 
^  0  and  a  new  b.  When  MO  ^  0,  then  it  is  assumed  that  A,  B,C,.  and  IP  have  not  been 
modified  and  that  X  contains  the  new  b.  The  routine  retrieves  from  A,  B,C,  and  IP  the 
block  decomposition  that  was  obtained  on  the  initial  call  to  BTSLV,  and  solves  the  new 
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system  of  equations  Tx  =  b.  The  solution  is  stored  in  X.  In  this  case,  IND  is  not  referenced 
by  the  routine. 

Programming.  BTSLV  employs  the  subroutines  DECBT,  SOLBT,  DEC,  and  SOL.  These 
subroutines  were  written  by  Alan  C.  Hindmarsh  (Lawrence  Livermore  Laboratory) . 

Reference.  Hindmarsh,  A.  C.,  Solution  of  Block-Tridiagonal  Systems  of  Linear  Alge¬ 
braic  Equations ,  Report  UCID-30150,  Lawrence  Livermore  Laboratory,  1977. 
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INVERTING  SYMMETRIC  REAL  MATRICES  AND  SOLVING 
SYMMETRIC  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


The  subroutines  SMSLV  and  DSMSLV  are  available  for  inverting  symmetric  real  matri¬ 
ces  A  and  solving  systems  of  real  linear  equations  AX  =  B.  SMSLV  handles  single  precision 
problems  and  DSMSLV  handles  double  precision  problems.  It  is  assumed  that  the  matrix 
A  is  in  packed  form.  If  the  inverse  of  A  is  computed,  then  the  inverse  is  a  symmetric  matrix 
which  will  be  stored  in  packed  form. 

Note.  All  eigenvalues  of  a  real  symmetric  matrix  A  are  real.  The  inertia  of  A  is  the  ordered 
triple  where  jr  is  the  number  of  positive  eigenvalues  of  A,  v  the  number  of  negative 

eigenvalues  of  A,  and  f  the  number  of  zero  eigenvalues  of  A.  Thus,  if  n  is  the  order  of  A 
then  it  +  v  +  f  =  n.  Also  A  is  positive  definite  (positive  semi-definite,  negative  definite, 
negative  semi-definite)  if  x  =  n  (v  =  0,v  =  n,x  =  0). 

CALL  SMSLV(MO,n,  m,  A,  B,  kb,  D, RCOND, INERT, IERR,IPVT,WK) 

CALL  DSMSLV(MO,n,  m,  A,  B,  kb,  D, RCOND, INERT, IERR,IPVT,WK) 

A  is  an  array  of  dimension  n(n  +  l)/2  containing  the  elements  of  a  packed  n  x  n 
symmetric  matrix  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed  and  stored 
in  A  in  packed  form.  If  MO  #  0  then  the  inverse  of  A  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  AX  =  B  is  solved  and  the  solution  X  is  stored  in  B.  If  m  <  0  then 
there  are  no  equations  to  be  solved.  In  this  case  B  is  ignored. 

The  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  kb  is  ignored. 

D  is  an  array  of  dimension  2.  When  either  routine  is  called  the  determinant  det(A)  of 
the  matrix  A  is  computed.  If  det(A)  =  d  •  10fc  where  1  <  |d|  <  10  and  k  an  integer,  then  d 
is  stored  in  D(l)  and  the  exponent  k  is  stored  in  floating  point  form  in  D(2). 

RCOND  is  a  variable.  When  either  routine  is  called,  the  routine  makes  an  estimate  c 
of  the  condition  number  of  the  matrix  A  (relative  to  the  L\  norm).  RCOND  is  assigned 
the  value  1/c. 

INERT  is  an  integer  array  of  dimension  3.  When  either  routine  is  called  the  inertia 
of  the  matrix  A  is  computed.  INERT(l)  is  set  to  the  number  of  positive  eigenvalues  of  A, 
INERT(2)  is  set  to  the  number  of  negative  eigenvalues,  and  INERT(3)  is  set  to  the  number 
of  zero  eigenvalues. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routines  for 
keeping  track  of  the  row  and  column  interchanges  that  are  made.  WK  is  array  of  dimension 
n  or  larger  that  is  used  as  a  work  space. 
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Remarks. 

(1)  If  SMSLV  is  called  then  it  is  assumed  that  A  and  B  are  real  matrices,  D  and  WK  are 
real  arrays,  and  RCOND  is  a  real  variable.  Otherwise,  if  DSMSLV  is  called  then  it  is 
assumed  that  A  and  B  are  double  precision  matrices,  D  and  WK  are  double  precision 
arrays,  and  RCOND  is  a  double  precision  variable. 

(2)  RCOND  satisfies  0  <  RCOND  <  1.  If  RCOND  »  10~fc  then  one  can  expect  the  results 
to  have  approximately  k  fewer  significant  digits  of  accuracy  than  the  elements  of  A. 
For  example,  if  SMSLV  is  used  to  invert  a  matrix  in  the  14  digit  CDC  single  precision 
arithmetic  and  RCOND  =  .4E— 3,  then  the  computed  coefficients  of  the  inverse  matrix 
should  normally  be  accurate  to  about  11  digits.  In  general,  RCOND  characterizes  how 
well  or  poorly  conditioned  the  problem  is.  If  RCOND  «  1  then  one  should  expect  the 
results  to  be  almost  as  accurate  as  the  original  data  A.  However,  if  RCOND  «  0  then 
one  should  expect  the  results  to  be  nonsense. 

(3)  The  data  in  A  is  destroyed. 


Error  Return.  IERR  is  an  integer  variable.  If  RCOND  is  sufficiently  large  so  that  1  + 
RCOND  >  1,  then  IERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1  +  RCOND 
=  1  then  IERR  is  set  to  1  and  the  routine  terminates.  In  this  case,  A  will  have  been  de¬ 
stroyed  but  B  will  not  have  been  modified.  Also  the  determinant  and  inertia  will  not  have 
been  computed. 

Algorithm.  The  diagonal  pivoting  factorization  procedure  is  used.  Partial  pivoting  is 
employed. 

Precision.  SMSLV  and  the  more  general  routine  MSLV  have  approximately  the  same  ac¬ 
curacy,  and  DSMSLV  and  DMSLV  have  approximately  the  same  accuracy. 

Efficiency.  Even  though  SMSLV  performs  approximately  half  the  number  of  multiplica¬ 
tions  and  divisions  as  MSLV,  normally  one  can  expect  SMSLV  to  take  about  70-80%  of  the 
time  required  by  MSLV.  However,  for  sparse  matrices  SMSLV  may  be  20-30%  slower  than 
MSLV.  Similar  comments  hold  for  DSMSLV  and  DMSLV. 

Programming.  SMSLV  and  DSMSLV  are  driver  routines  for  the  LINPACK  subroutines 
SSPCO,  SSPFA,  SSPSL,  SSPDI  and  DSPCO,  DSPFA,  DSPSL,  DSPDI.  SSPCO  and  DSPCO 
were  written  by  Cleve  Moler  (University  of  New  Mexico).  The  remaining  LINPACK  subrou¬ 
tines  were  written  by  James  Bunch  (University  of  California,  San  Diego).  The  subroutines 
employ  the  vector  routines  SCOPY,  SSWAP,  SDOT,  SSCAL,  SAXPY,  SASUM,  ISAMAX 
and  DSWAP,  DDOT,  DSCAL,  DAXPY,  DASUM,  IDAMAX. 

References. 

(1)  Bunch,  J.  R.  and  Parlett,  B.  N.,  “Direct  Methods  for  Solving  Symmetric  Indefinite 
Systems  of  Linear  Equations,”  SIAM  J.  Numerical  Analysts  8  (1971)  ,  pp.  639-655. 

(2)  Bunch,  J.  R.,  “Analysis  of  the  Diagonal  Pivoting  Method,”  SIAM  J.  Numerical  Anal¬ 
ysis  8  (1971),  pp.  656-680. 
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(3)  Bunch,  J.  R.,  Kaufman,  L.,  and  Parlett,  B.N.,  “Decomposition  of  a  Symmetric  Matrix,” 
Numerische  Mathematik  27  (1976),  pp.  95-109. 

(4)  Bunch,  J.,  and  Kaufman,  L.,  “Some  Stable  Methods  for  Calculating  Inertia  and  Solving 
Symmetric  Linear  Systems,”  Math.  Comp.  31  (1977),  pp.  163-179. 

(5)  Cline,  A.  K.,  Moler,  C.  B.,  Stewart,  G.  W.,  and  Wilkinson,  J.  H.,  “An  Estimate  for  the 
Condition  Number  of  a  Matrix,”  SIAM  Numerical  Analysis  16  (1979),  pp.  368-375. 

(6)  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK  Users’ 
Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 
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INVERTING  POSITIVE  DEFINITE  SYMMETRIC  MATRICES  AND  SOLVING 
POSITIVE  DEFINITE  SYMMETRIC  SYSTEMS  OF  LINEAR  EQUATIONS 


The  subroutines  PCHOL  and  DPCHOL  are  available  for  inverting  positive  definite 
symmetric  real  matrices  A  and  solving  systems  of  real  linear  equations  AX  =  B.  PCHOL 
handles  single  precision  problems  and  DPCHOL  handles  double  precision  problems.  It  is 
assumed  that  the  matrix  A  is  in  packed  form.  If  the  inverse  of  A  is  computed  then  the 
inverse  is  a  symmetric  matrix  which  will  be  stored  in  packed  form. 

CALL  PCHOL  (MO  ,n ,  m ,  A,  B  ,&6,IERR) 

CALL  DPCHOL(MO,n,  m,  A,  B, kb, IERR) 

A  is  an  array  of  dimension  n(n  +  l)/2  or  larger  containing  the  elements  of  a  packed 
n  x  n  positive  definite  symmetric  matrix  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is 
computed  and  stored  in  A  in  packed  form.  If  MO  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  AX  —  B  is  solved  and  the  solution  X  is  stored  in  B.  If  m  <  0  then 
there  are  no  equations  to  be  solved.  In  this  case  B  is  ignored. 

The  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  kb  is  ignored. 

Remarks. 

(1)  If  PCHOL  is  called  then  it  is  assumed  that  A  and  B  are  real  arrays,  and  if  DPCHOL 
is  called  then  it  is  assumed  that  A  and  B  are  double  precision  arrays. 

(2)  The  data  in  A  is  destroyed. 

Error  Return.  IERR  is  an  integer  variable.  If  A  is  positive  definite  then  IERR  is  set  to  0 
and  the  problem  is  solved.  Otherwise,  IERR  =  k  if  the  leading  kxk  submatrix  of  A  is  not 
positive  definite. 

Algorithm.  The  Cholesky  procedure  is  used. 

Precision.  The  results  obtained  by  PCHOL  and  DPCHOL  are  occasionally  less  accurate 
(up  to  1  significant  digit)  than  the  results  obtained  by  SMSLV  and  DSMSLV. 

Programming.  PCHOL  and  DPCHOL  are  driver  routines  for  the  LINPACK  subroutines 
SPPFA,  SPPSL,  SPPDI  and  DPPFA,  DPPSL,  DPPDI.  These  subroutines  were  written  by 
Cleve  Moler  (University  of  New  Mexico).  The  functions  SDOT,  DDOT  and  subroutines 
SAXPY,  SSCAL,  DAXPY,  DSCAL  are  also  used. 

Reference.  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK 
Users?  Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 
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SOLUTION  OF  TOEPLITZ  SYSTEMS  OF  LINEAR  EQUATIONS 

An  n  x  n  Toeplitz  matrix  is  a  matrix  of  the  form 


flo 

a-i 

a-2 

■  •  •  <*-n+l 

ao 

a-i 

...  <3— n+ 2 

a2 

ao 

. .  .  <2_n+ 3 

■n-1 

an- 2 

fln-3 

...  ap 

For  convenience,  we  denote  this  matrix  by  An  for  n  >  1.  If  An  is  a  real  matrix  where  a0  ^  0 
and  b  is  a  real  column  vector,  then  the  subroutines  TOPLX  and  DTOPLX  are  available 
for  solving  the  system  of  equations  Anx  =  b.  TOPLX  is  a  single  precision  routine  and 
DTOPLX  a  double  precision  routine. 

CALL  TOPLX(A,  b,  x,  n,G,  H ,IERR) 

CALL  DTO PLX(A, b, x,n,G, if, IERR) 

TOPLX  is  used  if  A ,  b,  x,  G,  H  are  real  arrays,  and  DTOPLX  is  used  if  A,  b,  x,  G,  H  are 
double  precision  arrays. 

A  is  an  array  of  dimension  2n- 1  or  larger  containing  the  coefficients  A(j)  ~  ay_„  (j  = 
1,  . . .  ,2n  —  1)  of  the  matrix  An.  The  argument  x  is  an  array  of  dimension  n  or  larger,  and 
IERR  is  an  integer  variable.  When  the  routine  is  called,  if  Anx  =  b  is  solved  then  IERR  is 
set  to  0  and  the  solution  is  stored  in  x.  A  and  b  are  not  modified  by  the  routine. 

G  and  H  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routine. 

Error  Return.  IERR  =  1  if  the  equations  cannot  be  solved  by  the  routine. 

Remarks.  The  Levinson  bordering  procedure  is  used.  This  procedure  is  inductive,  be¬ 
ginning  with  the  solution  x\  =  b\) a§  of  the  equation  clqXi  =  b\.  Given  a  solution  for 
EyLj ai-3Xj  =  bi  (»  =  1,  . . . ,  N)  where  N  <  n,  then  a  solution  for  E =  6,-  (:  = 
1,  . . . ,  N+ 1)  is  obtained  where  x1}  ... ,  xn+i  is  computed  from  x\,  ...,  Xff .  This  procedure 
fails  when  some  submatrix  An  is  singular  (e.g.,  when  a0  =  0).  Also,  the  procedure  may 
yield  poor  results  when  some  Ajv  is  exceedingly  ill-conditioned.  In  such  situations  one  must 
use  a  more  general  equation  solver.  In  TOPLX  and  DTOPLX  4(n  -  l)2  floating  additions 
and  4n(n  —  1)  integer/floating  multiplications  and  divisions  are  used  when  n  >  2.  Conse¬ 
quently,  these  routines  are  considerably  more  efficient  than  general  equation  solvers  such  as 
KROUT  and  DMSLV,  but  more  restrictive  and  frequently  less  accurate. 

Programming.  TOPLX  and  DTOPLX  are  modifications  by  A.  H.  Morris  of  the  subroutine 
TOEPLZ,  written  by  George  Rybicki. 

Reference.  Press,  W.  H.,  Flannery,  B.  P.,  Teukolsky,  S.  A.,  and  Vetterling,  W.  T.,  Nu¬ 
merical  Recipes:  The  Art  of  Scientific  Computing,  Cambridge  University  Press,  1986, 
pp.  47-52. 
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INVERTING  GENERAL  COMPLEX  MATRICES  AND  SOLVING 
GENERAL  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 

The  subroutines  CMSLV,  CMSLV1,  and  DCMSLV  are  available  for  inverting  complex 
matrices  and  solving  systems  of  complex  linear  equations.  CMSLV  and  CMSLV1  solve 
single  precision  problems  and  DCMSLV  solves  double  precision  problems. 

CALL  CMSLV(MO,n, m, A,ka, B,kb, D, RCOND, IERR,IPVT,WK) 

A  is  a  complex  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is 
computed  and  stored  in  A.  If  MO  ^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  complex  matrix  having  n  rows 
and  m  columns.  In  this  case  the  matrix  equation  AX  =  B  is  solved  and  the  solution  X  is 
stored  in  B.  If  m  ^  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument 
B  is  ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling 
program,  and  the  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in 
the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

D  is  a  complex  array  of  dimension  2.  When  CMSLV  is  called  the  determinant  det(A) 
of  the  matrix  A  is  computed."  If  det(A)  =  d  •  10*  where  1  <  |Re(d)j  +  |Im(d)|  <  10  and  k 
an  integer,  then  d  is  stored  in  D(l)  and  the  exponent  k  is  stored  as  a  complex  number  in 
0(2). 

RCOND  is  a  real  variable.  When  CMSLV  is  called,  the  routine  makes  an  estimate 
c  of  the  condition  number  of  the  matrix  A  (relative  to  the  modified  Lx  norm  where  each 
absolute  value  \z\  is  replaced  with  |Re(z)|  +  |Im(z)j).  RCOND  is  assigned  the  value  1/c. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routine  for  keeping 
track  of  the  row  interchanges  that  are  made.  WK  is  a  complex  array  of  dimension  n  or 
larger  that  is  used  as  a  work  space. 

Remarks. 

(1)  RCOND  satisfies  0  <  RCOND  <  1.  If  RCOND  «  10“ *  then  one  can  expect  the  results 
to  have  approximately  k  fewer  significant  digits  of  accuracy  than  the  elements  of  A. 
For  example,  if  CMSLV  is  used  to  invert  a  matrix  in  the  14  digit  CDC  single  precision 
arithmetic  and  RCOND  =  .41?— 3,  then  the  computed  coefficients  of  the  inverse  matrix 
should  normally  be  accurate  to  about  11  digits.  In  general,  RCOND  characterizes  how 
well  or  poorly  conditioned  the  problem  is.  If  RCOND  ss  1  then  one  should  expect  the 
results  to  be  almost  as  accurate  as  the  original  data  A.  However,  if  RCOND  «  0  then 
one  should  expect  the  results  to  be  nonsense. 

(2)  The  matrix  A  is  always  destroyed. 

Error  Return.  IERR  is  an  integer  variable.  If  RCOND  is  sufficiently  large  so  that  1  + 
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RCOND  >  1,  then  IERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1+RCOND  =  1 
then  IERR  is  set  to  1  and  the  routine  terminates.  In  this  case,  A  will  have  been  destroyed 
but  B  will  not  have  been  modified.  Also  the  determinant  will  not  have  been  computed. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used.  The  pivots  akj  are 
selected  so  that  |Re(afcy)|  +  |Im(afcy)|  =  max{|Re(a  ij)\  +  |Im(a,y)|  :i  =  j,  ...,n}. 

Programming.  CMSLV  calls  the  LINPACK  subroutines  CGECO,  CGEFA,  CGESL,  and 
CGEDI.  These  subroutines  were  written  by  Cleve  Moler  (University  of  New  Mexico).  The 
subroutines  CSWAP,  CSCAL,  CSSCAL,  CAXPY  and  functions  CDOTC,  SCASUM,  ICA- 
MAX  are  also  used. 

References. 

(1)  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK  Users’ 
Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 

(2)  Cline,  A.  K.,  Moler,  C.  B.,  Stewart,  G.  W.,  and  Wilkinson,  J.  H.,  “An  Estimate  for  the 
Condition  Number  of  a  Matrix,”  SIAM  Journal  of  Numerical  Analysis  16  (1979), 
pp.  368-375. 

CALL  CMSLVl(MO,n,  m,  A,  ka,  B,  fc&,IERR,IPVT,WK) 

A  is  a  complex  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is 
computed  and  stored  in  A.  If  MO  y£  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  complex  matrix  having  n  rows 
and  m  columns.  In  this  case  the  matrix  equation  AX  =  B  is  solved  and  the  solution  X  is 
stored  in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument 
B  is  ignored. 

The  argument  A:  a  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling 
program,  and  the  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in 
the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routines  for 
keeping  track  of  the  row  interchanges  that  are  made. 

WK  is  a  complex  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 
If  MO  yt  0  then  WK  is  ignored. 

Error  Return.  IERR  is  a  variable  that  reports  the  status  of  the  results.  When  CMSLV1 
terminates  IERR  has  one  of  the  following  values: 

IERR  =  0  The  requested  results  were  obtained. 

IERR  =  —  1  Either  n,ka,  or  kb  is  incorrect. 

IERR  =  k  The  kth  column  of  A  has  been  reduced  to  a  column  containing 
zeros.  The  requested  results  cannot  be  obtained. 
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Remarks. 

(1)  The  matrix  A  is  destroyed. 

(2)  CMSLV  and  CMSLV1  produce  the  same  results  for  X  and  the  inverse  of  A. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used.  The  pivots  akj  are 
selected  so  that  |Re(afcj)|  +  |Im(a*3)|  =  max  {|Re(aiy)|  +  |Im(oiy)|  :  t  =  j,  . . . ,  n}. 

Programming.  CMSLV1  calls  the  UNPACK  subroutines  CGEFA,  CGESL,  and  CGEDI. 
These  subroutines  were  written  by  Cleve  Moler  (University  of  New  Mexico).  The  subrou¬ 
tines  CSWAP,  CSCAL,  CAXPY  and  functions  CDOTC,  ICAMAX  are  also  used. 

Reference.  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  UNPACK 
Users1  Guide,  SIAM,  1979. 

CALL  DCMSLV(MO,n,  m,AR,AI,/fca,BR,BI,fc6,IERR,IPVT,WK) 

AR  and  AI  are  double  precision  matrices  of  order  »  >  1.  AR  and  AI  are  the  real  and 
imaginary  parts  of  the  complex  matrix  A  whose  inverse  is  to  be  computed  or  for  which 
AX  ~  B  is  to  be  solved.  If  MO  =  0  then  the  inverse  of  the  complex  matrix  is  computed 
and  the  results  stored  in  AR  and  AI.  If  MO  =£  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  BR  and  BI  are  double  precision  matrices 
having  n  rows  and  m  columns.  In  this  case,  BR  and  BI  are  the  real  and  imaginary  parts 
of  the  complex  matrix  B  for -which  AX  =  B  is  to  be  solved.  When  DCMSLV  is  called,  the 
real  and  imaginary  parts  of  the  solution  X  are  computed  and  stored  in  BR  and  BI.  If  m  <  0 
then  there  are  no  equations  to  be  solved.  In  this  case  BR  and  BI  are  ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statements  for  AR  and  AI  in 
the  calling  program,  and  the  argument  kb  is  the  number  of  rows  in  the  dimension  statements 
for  BR  and  BI  in  the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routine  for  keeping 
track  of  the  row  interchanges  that  are  made. 

WK  is  a  double  precision  array  of  dimension  2n  or  larger  that  is  a  work  space  for  the 
routine.  If  MO  ^  0  then  WK  is  ignored. 

Error  Return.  IERR  is  a  variable  that  reports  the  status  of  the  results.  When  DCMSLV 
terminates  IERR  has  one  of  the  following  values: 

IERR  =  0  The  requested  results  were  obtained. 

IERR  =  —  1  Either  n,ka,  or  kb  is  incorrect. 

IERR  =  k  The  kth  columns  of  AR  and  AI  have  been  reduced  to  columns 
containing  zeros.  The  requested  results  were  not  obtained. 

Remark.  The  matrices  AR  and  AI  are  destroyed. 
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Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used.  The  pivots  Akj  are 
selected  so  that  |Re(a*j)|  +  |Im(ofcy)|  =  max  {|Re(a,y)|  +  |Im(aj3-)|  :  *  =  j,  . . . ,  n}. 

Programming.  DCMSLV  ceJIs  the  subroutines  DCFACT,  DCSOL,  and  DCMINV.  These 
routines  were  written  by  A.  H.  Morris.  The  functions  CDIVID  and  DPMPAR  are  also 
used. 
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SOLUTION  OF  COMPLEX  EQUATIONS 
WITH  ITERATIVE  IMPROVEMENT 


Given  a  complex  n  x  n  matrix  A  and  a  complex  column  vector  b.  The  following  routine 
is  available  for  solving  the  equation  Ax  =  b.  Iterative  improvement  is  performed  to  compute 
the  solution  x  to  machine  accuracy. 

CALL  CSLVMP(MO,n,  A,  ka,  6,X,WK,IWK,IND) 

MO  is  an  input  argument  which  specifies  if  CSLVMP  is  being  called  for  the  first  time. 
On  an  initial  call,  MO  =  0  and  we  have  the  following  setup: 

A  is  a  2-dimensional  complex  array  of  dimension  ka  x  n  containing  the  matrix  A,  b  a 
complex  vector  of  dimension  n,  and  X  a  complex  array  of  dimension  n.  When  CSLVMP 
is  called,  Ax  =  b  is  solved  and  the  solution  stored  in  X.  A  and  b  are  not  modified  by  the 
routine. 

WK  is  a  complex  array  of  dimension  n2  +  n  or  larger,  and  IWK  an  integer  array  of 
dimension  n  or  larger.  These  arrays  are  for  internal  use  by  the  routine.  On  an  initial  call 
to  CSLVMP,  an  LU  decomposition  is  obtained  for  A  and  stored  in  WK  and  IWK.  Then  the 
equation  Ax  =  b  is  solved. 

IND  is  an  integer  variable  that  reports  the  status  of  the  results.  On  an  initial  call  to 
CSLVMP,  when  the  routine  terminates  IND  has  one  of  the  following  values: 

IND  =  0  The  solution  X  was  obtained  to  machine  accuracy. 

IND  =  1  X  was  obtained,  but  not  to  machine  accuracy. 

IND  =— k  The  kth  column  of  A  was  reduced  to  a  column  containing  only 
zeros.  In  this  case  no  solution  can  be  obtained. 

After  an  initial  call  to  CSLVMP,  if  IND  =  0  or  1  on  output,  then  the  routine  may  be 
called  to  solve  a  new  set  of  equations  Ax  —  b  without  having  to  redecompose  the  matrix 
A.  In  this  case,  the  input  argument  MO  may  be  set  to  any  nonzero  value.  When  MO  ^  0 
it  is  assumed  that  only  b  has  been  modified.  The  routine  employs  the  LU  decomposition 
obtained  on  the  initial  call  to  CSLVMP  to  solve  the  new  set  of  equations  Ax  —  b.  On 
output  X  will  contain  the  solution  to  the  new  set  of  equations.  As  before,  A  and  b  are  not 
modified  by  the  routine. 

If  CSLVMP  is  recalled  with  MO  yt  o,  then  when  the  routine  terminates  IND  has  one 
of  the  following  values: 

IND  =  0  The  solution  X  was  obtained  to  machine  accuracy. 

IND  =  1  X  was  obtained,  but  not  to  machine  accuracy. 

Programming.  CSLVMP  calls  the  subroutine  CLUIMP.  These  routines  were  written  by 
A.  H.  Morris.  The  subroutines  CMCOPY,  CGEFA,  CGESL,  CSCAL,  CAXPY  and  func¬ 
tions  SPMPAR,  CDOTC,  ICAMAX  are  also  employed. 
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SINGULAR  VALUE  DECOMPOSITION  OF  A  MATRIX 

If  A  is  a  complex  m  x  n  matrix  then  there  exists  an  m  X  m  unitary  matrix  U  and  an 
n  x  n  unitary  matrix  V  such  that  D  =  U*AV  is  a  diagonal  matrix1.  Let  d\,  ...  ,dk  be 
the  diagonal  elements  of  D  where  k  =  min{ m,n}.  Then  U  and  V  can  be  selected  so  that 
the  diagonal  elements  are  real  numbers  and  dx  >  d%  >  •  •  •  >  dk  >  0.  The  nonnegative 
diagonal  elements  d,  are  unique,  and  if  A  is  a  real  matrix  then  U  and  V  can  be  chosen  to 
be  real  orthogonal  matrices.  The  decomposition  D  =  U*AV  is  called  the  singular  value 
decomposition  of  A.  The  elements  d\,  . . .  ,dk  are  the  singular  values  of  A,  the  columns 
of  U  are  left  singular  vectors,  and  the  columns  of  V  are  right  singular  vectors. 

Remark.  For  m  >  n,  D  =  (^l )  where  Dx  =  diag(di,  . ..  ,dn ).  Consequently,  if  U  is 
partitioned  into  U  =  (?7x,  C/2)  where  Ux  has  n  columns,  then  it  follows  that  A  =  UDV *  = 
UXDXV*.  The  decomposition  A  =  UXDXV*  is  frequently  also  called  the  singular  value 
decomposition,  and  in  many  applications  it  suffices. 

The  following  subroutines  are  available  for  finding  the  singular  value  decomposition 
D  =  U*AV  of  a  matrix  A. 

CALL  SSVDC(A,  ka,  m,  n,  D,  E,  U,  ku,V,  kv, WORK, JOB, INFO) 

CALL  DSVDC(A,  ka,  m,  n,  D,  E,U, ku,  V,  fcv, WORK, JOB, INFO) 

CALL  CSVDC(A, ka, m,n,D,E, U, ku, V,kv, WORK, JOB, INFO) 

A  is  a  2-dimensional  array  of  dimension  ka  x  n  containing  the  m  x  n  matrix  whose 
singular  value  decomposition  is  to  be  computed.  D  is  an  array  of  dimension  min{m+ 1,  n}. 
When  any  of  the  routines  is  called,  the  singular  values  of  A  are  computed  and  stored  in 
descending  order  of  magnitude  in  D{  1),  . .  .,D{k)  where  k  =  min{m,n}. 

JOB  is  an  integer  that  controls  the  computation  of  the  singular  vectors.  It  is  assumed 
that  JOB  =  I  •  10  +  J  when  I,  J  =  0, 1,  ...  ,9.  I  and  J  have  the  following  meaning. 

1  =  0  Do  not  compute  the  left  singular  vectors. 

1=1  Compute  all  m  left  singular  vectors. 

I  >  1  Compute  the  first  min{m,n}  left  singular  vectors.  (Here  we  com¬ 
pute  the  decomposition  A  =  UiDxV*.) 

J  =  0  Do  not  compute  the  right  singular  vectors. 

J  >  0  Compute  the  right  singular  vectors. 

U  is  a  2-dimensional  array  which  contains  the  left  singular  vectors  that  are  requested, 
and  ku  is  the  number  of  rows  in  the  dimension  statement  for  U  in  the  calling  program.  It 
is  assumed  that  ku  >  m.  If  no  left  singular  vectors  are  requested  (i.e.,  if  JOB  <  10)  then  U 
is  ignored  by  the  routines.  Otherwise,  U  must  be  of  dimension  ku  x  m  if  all  m  left  singular 
vectors  are  requested,  and  U  must  be  of  dimension  ku  x  min{m,n}  if  the  first  min{m,n} 
left  singular  vectors  are  requested. 

lU *  denotes  the  adjoint  matrix  of  U. 
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V  is  a  2-dimensional  array  which  contains  the  right  singular  vectors  that  are  requested, 
and  kv  is  the  number  of  rows  in  the  dimension  statement  for  V  in  the  calling  program.  It 
is  assumed  that  kv  >  n.  If  no  right  singular  vectors  are  requested  then  V  is  ignored  by 
the  routines.  Otherwise,  V  must  be  of  dimension  kv  X  n  if  the  right  singular  vectors  are 
requested. 

E  is  an  array  of  dimension  n  or  larger,  and  WORK  is  an  array  of  dimension  m  or 
larger.  E  and  WORK  are  storage  areas  for  the  routines. 

Remarks. 

(1)  If  SSVDC  is  called  then  it  is  assumed  that  the  arrays  A,  D,  E,  17,  V, WORK  are  real 
arrays,  if  DSVDC  is  called  then  it  is  assumed  that  the  arrays  are  double  precision 
arrays,  and  if  CSVDC  is  called  then  it  is  assumed  that  the  arrays  are  complex  arrays. 

(2)  The  contents  of  A  are  destroyed  by  the  routines.  If  left  singular  vectors  are  requested 
and  there  is  sufficient  storage  in  A  to  hold  the  vectors  (there  will  be  sufficient  storage  if 
m  <  n  or  JOB  >  20),  then  one  may  set  U  =  A.  Similarly,  if  right  singular  vectors  are 
requested  and  m  >  n  then  one  may  set  V  —  A.  However,  only  one  of  the  two  arrays  U 
and  V  may  be  identified  with  A. 

Error  Return.  INFO  is  an  iteger  variable.  If  all  the  singular  values  are  found  then  INFO 
will  be  set  to  0  and  the  array  E  will  contain  zeros.  However,  if  the  jth  singular  value  cannot 
be  found  then  INFO  is  set  to  j.  In  this  case,  if  j  <  k  where  k  =  min{m,  n}  then  the  singular 
values  dj+i,  ...  ,dk  will  have  been  computed  and  stored  in  D.  A  will  have  been  reduced  to 
an  upper  bidiagonal  matrix  B  with  D  as  its  diagonal  and  E  its  super  diagonal.  If  U  and  V 
have  been  requested  then  B  =  U*AV  will  be  satisfied. 

Programming.  SSVDC,  DSVDC,  and  CSVDC  are  part  of  the  UNPACK  package  of  matrix 
subroutines  released  by  Argonne  National  Laboratory.  The  routines  were  coded  by  G.  W. 
Stewart  (University  of  Maryland).  The  routines  employ  the  vector  subroutines  SSWAP, 
SROT,  SDOT,  SSCAL,  SAXPY,  SNRM2,  DSWAP,  DROT,  DDOT,  DSCAL,  DAXPY, 
DNRM2,  and  CSWAP,  CSROT,  CDOTC,  CSCAL,  CAXPY,  SCNRM2.  Also  the  subrou¬ 
tines  SROTG  and  DROTG  are  called. 

Reference.  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK 
Users’  Guide ,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 
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EVALUATION  OF  THE  CHARACTERISTIC  POLYNOMIAL  OF  A  MATRIX 

The  following  functions  are  available  for  computing  the  determinant  of  A  —  xl  where 
A  is  an  n  x  n  matrix,  x  a  number,  and  I  the  n  x  n  identity  matrix. 

DET(A,  ka,n,x) 

DPDET(A,  ka,n,x) 

CDET(A, ka,  n,  x) 

DET  is  a  real  function  that  is  used  when  A  is  a  reed  matrix  and  x  a  real  number, 
DPDET  is  a  double  precision  function  that  is  used  when  A  is  a  double  precision  matrix 
and  x  a  double  precision  number,  and  CDET  is  a  complex  function  that  is  used  when  A  is 
a  complex  matrix  and  x  a  complex  number. 

The  value  of  the  appropriate  function  is  the  determinant  of  the  matrix  A  -  xl.  The 
argument  ka  has  the  value: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  n  >  1. 

Note.  A  is  destroyed  during  computation. 

Algorithm.  Gauss  partial  pivoting  is  performed  to  reduce  A  -  xl  to  upper  triangular 
form.  In  CDET  the  pivots  akj  are  selected  so  that  |Re(a*y)J  +  |Im(afcj)j  =  Max{|Re(aiy)j  + 
|Im(atJ)|  rather  than  \akj\  =  max{|aiy|  :  *  =  j,  . . . ,  n}. 

Programmer.  A.  H.  Morris 
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SOLUTION  OF  THE  MATRIX  EQUATION  AX  +  XB  =  C 


Given  an  m  X  m  matrix  A,nxn  matrix  B,  and  m  x  n  matrix  C.  The  subroutines 
ABSLV  and  DABSLV  are  available  for  obtaining  the  m  x  n  matrix  X  which  solves  the 
equation  AX  +  XB  =  C .  ABSLV  yields  single  precision  results  and  DABSLV  yields  double 
precision  results. 

CALL  ABSLV(MO,m,  n,  A,  ka,  B ,  kb,  C,  fcc,WK,IND) 

CALL  DABSLV  (MO, m,  n,  A,  ka,  B,  kb,  C,  kc, WK,IND) 

If  ABSLV  is  called  then  it  is  assumed  that  A,  B,  C,  and  WK  are  real  arrays.  Otherwise, 
if  DABSLV  is  called  then  it  is  assumed  that  A,  B,  C,  and  WK  axe  double  precision  arrays. 

It  is  assumed  that  m  >  1  and  n  >  1.  The  input  arguments  ka,  kb,  kc  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  required  that  ka  >  m,  kb  >  n,  kc>  m. 

WK  is  an  array  of  dimension  m2  +  n2  +  2k  or  larger  where  k  =  max{m,  n}.  WK  is  a 
general  storage  area  for  the  routine. 

MO  is  an  input  argument  which  specifies  if  the  routine  is  being  called  for  the  first  time. 
On  an  initial  call  MO  =  0.  In  this  case,  A  is  reduced  to  lower  real  Schur  form,  B  is  reduced 
to  upper  real  Schur  form,  and  then  the  transformed  system  of  equations  is  solved. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  has  one  of  the  following  values: 

IND  =  0  The  solution  was  obtained  and  stored  in  C. 

IND  =  1  The  equations  are  inconsistent  for  A  and  B. 

IND  =  —  1  A  could  not  be  reduced  to  lower  Schur  form. 

IND  =  —  2  B  could  not  be  reduced  to  upper  Schur  form. 

If  IND  7A  0  then  no  solution  is  obtained. 

When  IND  =  0,  A  contains  the  lower  Schur  form  of  the  matrix  A,  B  contains  the 
upper  Schur  form  of  the  matrix  B,  and  WK  contains  the  orthogonal  matrices  involved  in 
the  decompositions  of  A  and  B.  This  information  can  be  reused  to  solve  a  new  set  of 
equations.  The  following  options  are  available: 

MO  =  1  New  matrices  A  and  C  are  given.  The  data  for  B  is  reused  in 
solving  the  new  set  of  equations. 

MO  =  2  New  matrices  B  and  C  are  given.  The  data  for  A  is  reused  in 
solving  the  new  set  of  equations. 

MO  0, 1, 2  A  new  matrix  C  is  given.  The  data  for  A  and  B  is  reused  in 
solving  the  new  set  of  equations. 
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When  the  routine  is  recalled,  it  is  assumed  that  m,  n,  and  WK  have  not  been  modified. 

Programming.  ABSLV  employs  the  subroutines  ABSLV1,  ORTHES,  ORTRN1,  SCHUR, 
SHRSLV,  SLV,  and  DABSLV  employs  the  routines  DABSV1,  DORTH,  DRTRN1,  DSCHUR, 
DSHSLV,  DPSLV.  ABSLV  and  DABSLV  are  adaptations  by  A.  H.  Morris  of  the  subroutine 
AXPXB  written  by  R.  H.  Bartels  and  G.  W.  Stewart  (University  of  Texas  at  Austin). 

Reference.  Bartels,  R.  H.  and  Stewart,  G.  W.,  “Algorithm  432,  Solution  of  the  Matrix 
Equation  AX  +  XB  =  C,”  Comm.  ACM  15  (1972),  pp.  820-826. 
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SOLUTION  OF  THE  MATRIX  EQUATION  A*X  +  XA  =  C 
WHEN  C  IS  SYMMETRIC 

Given  matrices  A  and  C  of  order  n  where  C  is  symmetric.  Then  the  subroutines 
TASLV  and  DTASLV  are  available  for  obtaining  the  symmetric  matrix  X  which  solves  the 
equation  AtX  +  XA  —  C.  TASLV  yields  single  precision  results  and  DTASLV  yields  double 
precision  results. 

CALL  TAS  LV(MO,n,  A,  ka,  C,  fcc,WK,IND) 

CALL  DTASLV(MO,n,  A, ka, C, fee, WK,IND) 

If  TASLV  is  called  then  it  is  assumed  that  A,  C  and  WK  are  real  arrays.  Otherwise, 
if  DTASLV  is  called  then  it  is  assumed  that  A,  C ,  and  WK  are  double  precision  arrays. 

It  is  assumed  that  n  >  1.  The  input  arguments  ka  and  kc  have  the  following  values: 
ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  required  that  ka>  n  and  kc  >  n. 

WK  is  an  array  of  dimension  n2  +  2n  or  larger  that  is  a  general  storage  area  for  the 
routine. 

MO  is  an  input  argument  which  specifies  if  the  routine  is  being  called  for  the  first  time. 
On  an  initial  call  MO  =  0.  In. this  case,  A  is  reduced  to  upper  real  Schur  form  and  then 
the  transformed  system  of  equations  is  solved. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  has  one  of  the  following  values: 

IND  =  0  The  solution  was  obtained  and  stored  in  C. 

IND  =  1  The  equations  are  inconsistent. 

IND  =— 1  A  could  not  be  reduced  to  upper  Schur  form. 

If  IND  0  then  no  solution  is  obtained. 

When  IND  =  0,  A  contains  the  upper  Schur  form  of  the  matrix  A  and  WK  contains 
the  orthogonal  matrix  involved  in  the  decomposition  of  A.  This  data  can  be  reused  to  solve 
a  new  set  of  equations  AtX  +  XA  —  C .  In  this  case,  MO  can  be  set  to  any  nonzero  value. 
When  MO  #  0  it  is  assumed  that  only  C  has  been  modified.  When  the  routine  terminates, 
the  solution  for  the  new  set  of  equations  is  stored  in  C. 

Programming.  TASLV  employs  the  subroutines  TASLV1,  ORTHES,  ORTRN1,  SCHUR, 
SYMSLV,  SLV  and  DTASLV  employs  the  routines  DTAS V 1  ,DORTH,DRTRN  1  ,DSCHUR, 
DSYMSV,  DPSLV .  TASLV  and  DTASLV  are  adaptations  by  A.  H.  Morris  of  the  subroutine 
ATXPXA  written  by  R.  H.  Bartels  and  G.  W.  Stewart  (University  of  Texas  at  Austin). 

Reference.  Bartels,  R.  H.  and  Stewart,  G.  W.,  “Algorithm  432,  Solution  of  the  Matrix 
Equation  AX  +  XB  =  C Comm.  ACM  15  (1972),  pp,  820-826. 
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SOLUTION  OF  THE  MATRIX  EQUATION  AX2  +  BX  +  C  =  0 

Given  complex  n  x  n  matrices  A,  B,  and  C.  The  following  subroutine  is  available  for 
obtaining  a  complex  n  X  n  matrix  X  which  solves  the  equation  AX'2  +  BX  +  (7  =  0. 

CALL  SQUINT(m, n,  A, B, C, IND,X,WK,£, r, MAX, IERR) 

It  is  assumed  that  A,  B,  C,  and  X  are  2-dimensional  complex  arrays  of  dimension  m  x  n 
where  m  >  n.  When  SQUINT  is  called,  the  n  X  n  complex  matrix  solution  obtained  for 
AX2  +  BX  +  C  —  0  is  stored  in  X.  A,  B,  and  C  are  modified  by  the  routine. 

IND  is  an  integer  variable.  On  input,  if  IND  ±  0  then  it  is  assumed  that  an  initial 
approximation  for  the  desired  solution  is  provided  in  X  by  the  user.  Otherwise,  if  IND 
=  0  then  the  routine  provides  its  own  initial  approximation.  Then  Newton  iteration  is 
performed.  On  output,  IND  =  the  number  of  iterations  that  were  performed  to  compute  X. 

WK  is  a  complex  array  of  dimension  i  that  is  a  work  space  for  the  routine.  It  is 
assumed  that  t  >  7n2  +  n.  When  SQUINT  terminates,  WK(l)  is  a  complex  number  whose 
real  part  is  the  norm  ||AX2  +  BX  +  Cjloo. 

The  argument  r  is  a  real  number.  If  r  <  0  then  X  is  computed  to  machine  precision. 
Otherwise,  if  t  >  0  then  iteration  terminates  when  ||AX2  +  BX  +  C\\  <  t. 

MAX  is  a  variable.  If  MAX  >  0  then  MAX  is  the  maximum  number  of  iterations  that 
may  be  performed.  If  MAX  <  0  then  it  is  reset  by  the  routine  to  30,  the  default  maximum 
number  of  iterations. 

Error  Return.  IERR  is  a  variable  that  is  set  by  the  routine.  If  a  solution  X  is  obtained, 
then  IERR  is  assigned  the  value  0.  Otherwise,  IERR  has  one  of  the  following  values: 

IERR  =  1  MAX  iterations  were  performed.  More  iterations  are 
needed. 

IERR  =  2, 3  Factorization  of  the  equations  could  not  be  completed. 

X  cannot  be  computed. 

IERR  =  10  +  n  Newton  iteration  failed  on  iteration  n.  Possibly  too  much 
accuracy  was  requested.  X  cannot  be  computed. 

IERR  =  999  (Input  Error)  Either  n<l,m<n,  or£<  7  n2  +  n. 

When  IERR  =  1  occurs,  X  contains  the  most  recent  value  obtained  for  the  solution  and 
WK(1)  is  a  complex  number  whose  real  part  is  the  latest  value  obtained  for  the  norm 
|[AX2  +  BX  +  CHoo. 

Programming.  SQUINT  employs  the  subroutines  SQUIN2,  CQZHES,  CQZIT,  TRISLV, 
and  CTRANS.  These  routines  were  designed  by  George  J.  Davis  (Georgia  State  University, 
Atlanta,  Georgia).  CQZHES  and  CQZIT  are  modifications  of  the  EISPACK  subroutines 
QZHES  and  QZIT,  developed  at  Argonne  National  Laboratory.  The  function  SPMPAR  is 
also  used. 
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EXPONENTIAL  OF  A  REAL  MATRIX 


Let  A  be  a  real  matrix  of  order  n  >  1.  Then  the  subroutines  MEXP  and  DMEXP 

°o 

are  available  for  computing  the  exponential  matrix  eA  =  Ai/ *!.  MEXP  yields  single 

t-0 

precision  results  and  DMEXP  yields  double  precision  results. 

CALL  MEXP  (A,  ka,  n,  Z,  fcz,WK,IERR) 

A  is  a  real  matrix  of  order  n  >  1  and  Z  a  real  2-dimensional  array.  MEXP  computes 
eA  and  stores  the  results  in  Z.  The  arguments  ka  and  kz  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kz  =  the  number  of  rows  in  the  dimension  statement  for  Z  in  the  calling  program 
It  is  assumed  that  ka  >  n,  kz  >  n,  and  that  A  and  Z  are  different  storage  areas.  If  n  >  1 
then  A  is  destroyed. 

WK  is  a  real  array  of  dimension  n(n  +  8)  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  MEXP  terminates, 
IERR  is  assigned  one  of  the  following  values: 

IERR  =  0  The  exponential  was  computed. 

IERR  =  1  The  norm  ||Af|i  =  max3X)i  la*'/l  to°  large.  eA  cannot  be  com¬ 
puted. 

IERR  =  2  The  Pade  denominator  matrix  is  singular.  (This  should  never 
occur.) 

Algorithm.  A  is  balanced,  yielding  a  matrix  B  =  D~1PiAPD  where  D  is  a  diagonal  matrix, 
P  a  permutation  matrix,  and  ||J9||i  <  ||A||i.  Next  m  is  set  to  the  smallest  nonnegative 
integer  such  that  min{||J3f|i,  ||23||oo}  <  2m,  and  the  8th’  diagonal  Pade  approximation  for 
ex  is  used  to  compute  exp (S/2m).  Then  eB  =  [exp(B/2m)]Sm  is  obtained  by  m  squarings, 
and  eA  =  PDeBD~1Pt  is  applied. 

Programming.  MEXP  calls  the  subroutines  BALANC,  BALENV,  and  SLV.  The  function 
IPMPAR  is  also  used.  MEXP  was  written  by  A.  H.  Morris. 

Reference.  Ward,  Robert,  C.,  “Numerical  Computation  of  the  Matrix  Exponential  with 
Accuracy  Estimate,”  SIAM  J.  Numerical  Analysis  14  (1977),  pp.  600-610 

CALL  DMEXP(A,  fca,n,iJ,A:z,WK,IERR) 

A  is  a  double  precision  matrix  of  order  n  >  1  and  Z  a  double  precision  2-dimensional 
array.  DMEXP  computes  eA  and  stores  the  results  in  Z.  The  arguments  ka  and  kz  have 
the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kz  =  the  number  of  rows  in  the  dimension  statement  for  Z  in  the  calling  program 


227 


It  is  assumed  that  ka  >  n,  kz  >  n,  and  that  A  and  Z  are  different  storage  areas.  If  n  >  1 
then  A  is  destroyed. 

WK  is  a  double  precision  array  of  dimension  n(n  +  12)  or  larger  that  is  a  work  space 
for  the  routine. 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  DMEXP  terminates, 
IERR  is  assigned  one  of  the  following  values: 

IERR  =  0  The  exponential  was  computed. 

IERR  =  1  The  norm  ||A||i  is  too  large.  eA  cannot  be  computed. 

IERR  =  2  The  Pade  denominator  matrix  is  singular.  (This  should  never 
occur.) 

Programming.  DMEXP  calls  the  subroutines  DEAL,  DBALNV,  and  DPSLV.  The  function 
IPMPAR  is  also  used.  DMEXP  was  written  by  A.  H.  Morris. 

Reference.  Ward,  Robert  C.,  “Numerical  Computation  of  the  Matrix  Exponential  with 
Accuracy  Estimate,”  SIAM  J.  Numerical  Analysis  14  (1977),  pp.  600-610 
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SOLVING  SYSTEMS  OF  200-400  LINEAR  EQUATIONS 


For  n  >  1,  let  A  denote  an  n  X  n  matrix  and  b  a  column  vector  of  dimension  n.  Then 
the  subroutines  LE,  DPLE,  and  CLE  are  available  for  solving  the  equations  Ax  =  b  where  A 
is  not  stored  in-core.  For  large  n,  these  routines  require  a  work  space  of  dimension  «  n2 /4. 
This  permits  the  solution  of  systems  of  equations  of  double  the  order  permitted  by  the 
standard  solution  procedures. 

CALL  LE(RO WK,n,  b,  XWK, IWK, IERR) 

CALL  DPLE(ROWK,n,&,X,WK,IWK,IERR) 

CALL  CLE(ROWK,n,  6,  X,WK, IWK, IERR) 

X  is  an  array  of  dimension  n  and  IERR  an  integer  variable.  When  the  equations  are 
solved,  then  IERR  is  set  to  0  and  the  solution  is  stored  in  X. 

ROWK  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  ROWK(n,  k,  R) 

R  is  an  array  of  dimension  n  and  k  =  1,  . . . ,  n.  When  ROWK  is  called,  the  ktK  row  of  the 
matrix  A  is  stored  in  R.  ROWK  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

WK  is  an  array  of  dimension  [n2  / 4]  +  n  +  3  or  larger,1  and  IWK  is  an  integer  array  of 
dimension  max{l,  rt  —  1}  or  larger.  WK  and  IWK  are  work  spaces  for  the  routines. 

Error  Return.  IERR  =  k  when  the  first  k  rows  of  A  are  found  to  be  linearly  dependent. 

Remarks. 

(1)  When  LE  is  called  then  it  is  assumed  that  b ,  X,  WK  and  the  array  R  in  ROWK  are  real 
arrays.  When  DPLE  is  called  then  it  is  assumed  that  these  arrays  are  double  precision 
arrays,  and  when  CLE  is  called  then  it  is  assumed  that  the'  arrays  are  complex. 

(2)  When  the  equations  are  solved,  ROWK  is  called  to  attach  the  first  row  of  A,  then  the 
second  row,  etc.  Each  row  of  A  is  attached  only  once. 

(3)  The  array  b  is  not  modified  by  the  routines. 

Example.  Consider  a  system  of  n  =  300  real  linear  equations  Ax  =  b  where  the  rows  of  A 
are  stored,  one  row  per  logical  record,  in  sequence  in  an  unformatted  file  (say  file  4).  Then 
the  following  code  can  be  used  to  solve  the  equations: 

REAL  B(300),X(300),WK(22803) 

INTEGER  IWK  (300) 

EXTERNAL  GETROW 
DATA  N/300/ 


1Here  [n2/ 4]  denotes  the  largest  integer  <  n2/4. 
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REWIND  4 

CALL  LE(GETROW,N,B,X,WK,IWK,IERR) 

Here  GETROW  may  be  defined  by: 

SUBROUTINE  GETROW (N, I, R) 

REAL  R(N) 

READ  (4)  (R(J),J=1,N) 

RETURN 

END 

Algorithm.  The  partial  pivot  Henderson- Wassyng  procedure  is  used. 

Programming.  LE,  DPLE,  and  CLE  are  modified  versions  (by  A.  H.  Morris)  of  the  subrou¬ 
tine  TE,  written  by  A:  Wassyng  (University  of  the  Witwatersrand,  Johannesburg,  South 
Africa) . 

Reference.  Wassyng,  A.,  “Solving  Ax  =  b:  A  Method  with  Reduced  Storage  Require¬ 
ments,”  SIAM  J.  Numerical  Analysis  19  (1982),  pp.  197-204. 
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BAND  MATRIX  STORAGE 


For  an  m  x  n  matrix  A  =  (a,y),  let  mi  be  the  number  of  diagonals  below  the  main 
diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the  main 
diagonal  containing  nonzero  elements.  Then  m/  and  mu  are  called  the  lower  and  upper 
band  widths  of  A,  and  mt+mu  + 1  the  total  band  width  of  A.  It  is  clear  that  0  <  mt  <  m 
and  0  <  mu  <  n,  and  that  a,y  ^  0  only  when  *  —  mi  <  j  <  t  +  mu.  If  the  band  width 
mi  +  mu  +  1  is  sufficiently  small,  then  it  is  also  clear  that  a  considerable  savings  in  storage 
can  occur  by  storing  only  the  nonzero  diagonals  of  A.  The  band  storage  scheme  adopted  by 
the  NSWC  library  is  to  store  A  as  an  m  x  ( mt  +  mu  +  1)  matrix  B  =  (6ifc).  The  columns 
of  B  are  the  nonzero  diagonals  of  A.  Specifically,  for  each  nonzero  a,y,  =  a,y  where 
k  =  j  —  i  +  mi  +  1.  The  remaining  &,•*’ s  are  zeros. 

Example.  Consider  the  matrix 
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where  mi  =  1  and  m0  =  2.  Then  A  will  be  stored  in  band  form  as  follows 
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Remark.  The  first  mi  columns  of  B  contain  the  nonzero  diagonals  of  A  below  the  main 
diagonal,  the  (m<+  l)at  column  of  B  contains  the  main  diagonal,  and  the  last  mu  columns 
of  B  contain  the  nonzero  diagonals  of  A  above  the  main  diagonal. 
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CONVERSION  OF  BANDED  MATRICES  TO  AND  FROM 
THE  STANDARD  FORMAT 

The  following  subroutines  permit  one  to  convert  matrices  to  and  from  the  standard 
format. 


CALL  CVBR(A,  ka,  m,n,  mi,  mu,B,kb) 

CALL  CVBC (A,ka,m,n,mt,mu,B,kb) 

A  is  an  m  x  n  matrix  stored  in  band  form,  mt  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,  0  < 
m„  <  n,  and  ka  >  m. 

B  is  a  2-dimensional  array  of  dimension  kb  x  n  where  kb  >  m.  CVBR  is  used  if  A  and 
B  are  real  arrays,  and  CVBC  is  used  if  A  and  B  are  complex  arrays.  When  the  routine  is 
called,  the  matrix  A  is  stored  in  the  array  B  in  the  standard  format. 

Remark.  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location  then  it  is 
assumed  that  kb  =  ka.  In  this  case,  the  result  B  will  overwrite  the  input  data  A.  Otherwise, 
if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  assumed  that  the  storage  areas  A 
and  B  dp  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  CVRB (A,ka,m,n,mt,mu,B,kb) 

CALL  CVCB(A,  ka,  m,  n,  mi,  mu,  B,  kb) 

A  is  an  m  x  n  matrix  stored  in  the  standard  format,  and  and  mu  are  integers 
such  that  0  <  mi  <  m  and  0  <  mu  <  n.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  ka  >  m. 

B  is  a  2-dimension  array  of  dimension  kb  X  £  where  kb  >  m  and  £  >  mt  +  mu  +  1. 
CVRB  is  used  if  A  and  B  are  real  arrays,  and  CVCB  is  used  if  A  and  B  are  complex  arrays. 
When  the  routine  is  called,  the  mt  diagonals  of  A  immediately  below  the  main  diagonal, 
the  main  diagonal,  and  the  mu  diagonals  immediately  above  the  main  diagonal  are  stored 
in  band  form  in  B. 

Remarks. 

(1)  Given  a  matrix  A  =  (aty),  then  these  routines  may  be  used  to  convert  A  to  band  form 
when  the  lower  and  upper  bandwidths  mt  and  mu  of  A  are  known.  If  mt  and  mu  are 
not  known,  then  the  subroutines  CVRB1  and  CVCB1  described -below  can  be  used  to 
convert  A  to  band  form. 

(2)  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location  then  it  is 
assumed  that  kb  =  ka.  In  this  case,  the  result  B  will  overwrite  the  input  data  A. 
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Otherwise,  if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  assumed  that  the 
storage  areas  A  and  B  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  CVRB1(A,  ka,  m,  n,  mi, mu,  B , kb, £,IERR) 

CALL  CVCB1(A,  ka,m,  n,  mi,  mu,  IERR) 

A  is  an  m  x  n  matrix  stored  in  the  standard  format.  The  argument  ka  is  the 
number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed 
that  A  is  to  be  stored  in  band  form  in  B.  B  is  a  2-dimensional  array  of  dimension  kbx£ 
where  kb  >  m.  The  argument  t  is  an  estimate  of  the  maximum  number  of  diagonals 
of  A  that  will  have  to  be  stored. 

CVRB1  is  used  if  A  and  B  are  real  arrays,  and  CVCB1  is  used  if  A  and  B 
are  complex  arrays.  IERR,  mj,  and  mu  are  integer  variables.  When  the  routine  is 
called,  if  £  specifies  sufficient  storage  for  B  then  A  is  stored  in  band  form  in  B.  Also 
IERR  is  assigned  the  value  0,  mi  =  the  number  of  diagonals  of  A  below  the  main 
diagonal  containing  nonzero  elements,  and  mu  —  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  B,  then  IERR  is  assigned  the 
value  mi  +  mu  +  1.  Reset  £  >  IERR. 

Remark.  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location 
then  it  is  assumed  that  kb  =  ka.  In  this  case,  the  result  B  will  overwrite  the  input 
data  A.  Otherwise,  if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  assumed 
that  the  storage  areas  A  and  B  do  not  overlap. 

Programming.  CVRB1  calls  the  subroutine  CVRB,  and  CVCB1  calls  the  subroutine 
CVCB.  These  routines  were  written  by  A.  H.  Morris. 
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CONVERSION  OF  BANDED  MATRICES 
TO  AND  FROM  SPARSE  FORM 


The  following  subroutines  permit  one  to  convert  matrices  to  and  from  sparse  form. 

CALL  MCVBS(A,  ka,  m,  n,  mt,  mu,B,IB,JB,N UM.IERR) 

CALL  CMCVBS(A,  ka,  m,  n,  mt, mu,  B,IB, JB,NUM,IERR) 

A  is  an  m  X  n  matrix  stored  in  band  form,  m<  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statment  for  A  in  the  calling  program.  It  is  assumed  that  0  <  <  m,0  < 

mu  <  n,  and  ka  >  m. 

It  is  assumed  that  A  is  to  be  stored  in  sparse  form  in  the  arrays  B,IB,JB.  NUM  is 
the  estimated  maximum  number  of  elements  that  will  appear  in  B  and  JB.  It  is  assumed 
that  B  and  JB  are  of  dimension  max{l,NUM}  and  that  IB  is  of  dimension  m  +  1. 

MCVBS  is  used  if  A  and  B  are  real  arrays,  and  CMCVBS  is  used  if  A  and  B  are 
complex  arrays.  IERR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies 
sufficient  storage  for  B  and  JB,  then  IERR  is  assigned  the  value  0  and  A  is  stored  in  sparse 
form  in  B,  IB,  JB. 

Error  Return.  If  there  is  not  sufficient  storage  in  B  and  JB  for  the  ith  row  of  A,  then  IERR 
is  set  to  *  and  the  routine  terminates.  In  this  case,  if  *  >  1  then  the  first  i  —  1  rows  of  A 
will  have  been  stored  in  B  and  JB.  Also  IB(  1),  . . . ,  IB(i)  will  contain  the  appropriate  row 
locations. 

CALL  MCVSB(A,  I  A,  JA,m,  n,  B,  kb,  l,  mt,  mu,IERR) 

CALL  CMCVSB(A,/A, JA,m,  n,  B,  kb,  t,mi,  mu,IERR) 

A  is  an  m  x  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  It  is  assumed  that  A  is  to 
be  stored  in  band  form  in  B.  B  is  a  2-dimensional  array  of  dimension  kb  x  l  where  kb  >  m. 
The  argument  £  is  an  estimate  of  the  maximum  number  of  diagonals  of  A  that  will  have  to 
be  stored. 

MCVSB  is  used  if  A  and  B  are  real  arrays,  and  CMCVSB  is  used  if  A  and  B  are 
complex  arrays.  IERR,  mt,  and  mu  are  integer  variables.  When  the  routine  is  called,  if  £ 
specifies  sufficient  storage  for  B  then  A  is  stored  in  band  form  in  B.  Also  IERR  is  assigned 
the  value  0,  mi  =  the  number  of  diagonals  of  A  below  the  main  diagonal  containing  nonzero 
elements,  and  mu  =  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  B,  then  IERR  is  assigned  the  value 
mt  +  mu  +  1.  Reset  £  >  IERR. 

Programmer.  A.  H.  Morris 
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TRANSPOSING  BANDED  MATRICES 


The  following  subroutines  are  available  for  transposing  banded  matrices. 

CALL  BPOSE(A,  ka,  m,n,  mi,  mu,B,  kb) 

CALL  CBPOSE(A,  fca,m,  n,mi,mu,B,kb) 

A  is  an  m  x  n  matrix  stored  in  band  form,  m£  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  m<  <  m,0  < 
mu  <  n,  and  ka  >  m. 

B  is  a  2-dimensional  array  of  dimension  kb  x  £  where  kb  >  n  and  £  >  m£  +  mu  +  1. 
BPOSE  is  used  if  A  and  B  are  real  arrays,  and  CBPOSE  is  used  if  A  and  B  are  complex 
arrays.  When  the  routine  is  called,  the  transpose  A*  of  A  is  stored  in  band  form  in  B. 

Note.  It  is  assumed  that  the  storage  areas  A  and  B  do  not  overlap. 

Programmer.  A.  H.  Morris. 
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ADDITION  OF  BANDED  MATRICES 


Let  A  and  B  be  m  x  n  matrices  stored  in  band  form.  The  following  subroutines  are 
available  for  computing  the  sum  C  =  A  +  B. 

CALL  BADD(m,  n,  A,  ka,  m£,  mn,B,  kb,  nt ,  nu ,  C,  kc,  £,  vt,  i/u,IERR) 

CALL  CBADD(m,  n,  A,  ka,  mt,  mu,B,  kb,  nt,  nu,  C,  kc,  £,  vt,  r/u,IERR) 

A  and  B  are  m  X  n  matrices  stored  in  band  form,  mt  the  number  of  diagonals  of  A 
below  the  main  diagonal  containing  nonzero  elements,  mu  the  number  of  diagonals  of  A 
above  the  main  diagonal  containing  nonzero  elements,  nt  the  number  of  diagonals  of  B 
below  the  main  diagonal  containing  nonzero  elements,  and  nu  the  number  of  diagonals  of  B 
above  the  main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of 
rows  in  the  dimension  statement  for  A  in  the  calling  program,  and  kb  the  number  of  rows 
in  the  dimension  statement  for  B  in  the  calling  program. 

It  is  assumed  that  A  +  B  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional 
array  of  dimension  kc  x  £  where  kc  >  m.  The  input  argument  £  is  an  estimate  of  the 
maximum  number  of  diagonals  of  A  +  B  which  will  have  to  be  stored  (£  <  max{m^,  ni}  + 
max{mu,nu}  +  1).  BADD  is  used  if  A  and  B  are  real  arrays,  and  CBADD  is  used  if  A  and 
B  are  complex  arrays.  IERR,  vt,  and  vu  are  integer  variables.  When  the  routine  is  called, 
if  £  specifies  sufficient  storage  for  C  then  A  +  B  is  computed  and  stored  in  band  form  in  C. 
Also  IERR  is  assigned  the  value' 0,  vt  =  the  number  of  diagonals  of  A  +  B  below  the  main 
diagonal  containing  nonzero  elements,  and  i/u  =  the  number  of  diagonals  of  A  +  B  above 
the  main  diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  C,  then  IERR  is  assigned  the  value 
v  where  v  is  an  estimate  of  the  number  of  columns  needed  for  C.  Reset  £  >  v. 

Remarks.  If  mt  >  nt  then  C  may  begin  in  the  same  location  as  A.  If  C  begins  in  the  same 
location  as  A,  then  it  is  assumed  that  kc  =  ka  and  that  the  arrays  A  and  B  do  not  overlap. 
In  this  case,  the  result  C  will  overwrite  the  input  data  A.  Similarly,  if  mi  <  ni  then  C  may 
begin  in  the  same  location  as  B  when  kc  =  kb  and  A  and  B  do  not  overlap.  Otherwise,  if  C 
does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the  storage  area  for 
C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there  is  no  restriction 
on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Example.  If  B  =  -A  then  £  may  be  assigned  any  value  >  1.  In  this  case,  C  will  contain 
only  the  main  diagonal  of  the  zero  matrix  A  +  B,  and  vt  —  i/u  =  0. 

Programmer.  A.  H.  Morris 
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SUBTRACTION  OF  BANDED  MATRICES 


Let  A  and  B  be  m  x  it  matrices  stored  in  band  form.  The  following  subroutines  are 
available  for  computing  the  difference  C  =  A  —  B. 

CALL  BSUBT(m,  n,  A,  ka,  mt,  mu,B,  kb,  nt, nu, C,  kc,  £,  vt ,  i/u,IERR) 

C ALL  CB S U B T (m,  n,  A,  ka,  mt,  mu ,  B,  kb,  nt,  nu ,  C,  kc,  £,  vt,  vu ,IERR) 

A  and  B  are  m  X  n  matrices  stored  in  band  form,  mt  the  number  of  diagonals  of  A 
below  the  main  diagonal  containing  nonzero  elements,  mu  the  number  of  diagonals  of  A 
above  the  main  diagonal  containing  nonzero  elements,  ri£  the  number  of  diagonals  of  B 
below  the  main  diagonal  containing  nonzero  elements,  and  nu  the  number  of  diagonals  of  B 
above  the  main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of 
rows  in  the  dimension  statement  for  A  in  the  calling  program,  and  kb  the  number  of  rows 
in  the  dimension  statement  for  B  in  the  calling  program. 

It  is  assumed  that  A  -  B  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional 
array  of  dimension  kc  X  £  where  kc  >  m.  The  input  argument  £  is  an  estimate  of  the 
maximum  number  of  diagonals  of  A  -  B  which  will  have  to  be  stored  (£  <  max{mt,  nt}  + 
max{m„,nu}  +  1).  BSUBT  is  used  if  A  and  B  are  real  arrays,  and  CBSUBT  is  used  if  A 
and  B  are  complex  arrays.  IERR,  vt,  and  vu  are  integer  variables.  When  the  routine  is 
called,  if  £  specifies  sufficient  storage  for  C  then  A-  B  is  computed  and  stored  in  band  form 
in  C.  Also  IERR  is  assigned  the  value  0,  vt  =  the  number  of  diagonals  of  A-  B  below  the 
main  diagonal  containing  nonzero  elements,  and  vu  =  the  number  of  diagonals  of  A  -  B 
above  the  main  diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  C,  then  IERR  is  assigned  the  value 
v  where  v  is  an  estimate  of  the  number  of  columns  needed  for  C.  Reset  £  >  v. 

Remarks.  If  mt  >  nt  then  C  may  begin  in  the  same  location  as  A.  If  C  begins  in  the  same 
location  as  A,  then  it  is  assumed  that  kc  =  ka  and  that  the  arrays  A  and  B  do  not  overlap. 
In  this  case,  the  result  C  will  overwrite  the  input  data  A.  Similarly,  if  mt  <  nt  then  C  may 
begin  in  the  same  location  as  B  when  kc  =  kb  and  A  and  B  do  not  overlap.  Otherwise,  if  C 
does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the  storage  area  for 
C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there  is  no  restriction 
on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Example.  If  B  =  A  then  £  may  be  assigned  any  value  >  1.  In  this  case,  C  will  contain  only 
the  main  diagonal  of  the  zero  matrix  A  -  B,  and  vL  —  vu=  0. 

Programmer.  A.  H.  Morris 
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MULTIPLICATION  OF  BANDED  MATRICES 

Let  A  and  B  be  matrices  stored  in  band  form.  The  following  subroutines  are  available 
for  computing  the  product  C  =  AB. 

CALL  BPROD(m,n,£, A, ka, mi, mu,B, kb, nt,nu,C,kc,nc,i/t,i/u, IERR) 

CALL  CBPROD(m,n,£,  A,  ka,  mt,  mu,  B,  kb,  nt,  nu,C,  kc, nc,  vt,  i/u,IERR) 

A  is  an  m  x  n  matrix  stored  in  band  form,  mt  the  number  of  diagonals  of  A  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  of  A  above  the 
main  diagonal  containing  nonzero  elements.  B  is  an  n  x  £  matrix  stored  in  band  form,  nt 
the  number  of  diagonals  of  B  below  the  main  diagonal  containing  nonzero  elements,  and  nu 
the  number  of  diagonals  of  B  above  the  main  diagonal  containing  nonzero  elements.  The 
argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program, 
and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program.  It  is 
assumed  that  ka  >  m  and  kb  >  n. 

It  is  assumed  that  AB  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional  array  of 
dimension  kc  x  nc  where  kc  >  m.  The  input  argument  nc  is  an  estimate  of  the  maximum 
number  of  diagonals  of  AB  which  will  have  to  be  stored  (nc  <  min{n- 1,  mi+ni}+min{£- 
1,  mu  +  nu}  +  1).  BPROD  is  used  if  A,B,  and  C  are  real  arrays,  and  CBPROD  is  used  if 
A,B,  and  C  are  complex  arrays.  IERR,  vt,  and  vu  are  integer  variables.  When  the  routine 
is  called,  if  nc  specifies  sufficient  storage  for  C  then  AB  is  computed  and  stored  in  band 
form  in  C.  Also,  IERR  is  assigned  the  value  0,  vt  =  the  number  of  diagonals  of  AB  below 
the  main  diagonal  containing  nonzero  elements,  and  i/„  =  the  number  of  diagonals  of  AB 
above  the  main  diagonal  containing  nonzero  elements. 

Error  Return.  If  nc  does  not  specify  sufficient  storage  for  C,  then  IERR  is  assigned  the 
value  v  where  v  is  an  estimate  of  the  number  of  columns  needed  for  C.  Reset  nc  >  u. 

Note.  It  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for 
A  and  B. 

Programmer.  A.  H.  Morris 
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PRODUCT  OF  A  REAL  BANDED  MATRIX  AND  VECTOR 

Let  A  be  a  real  m  x  n  matrix  stored  in  band  form.  Then  the  following  subroutines  are 
available  for  multiplying  A  with  a  real  vector. 

CALL  BVPRD(m,  n,  A,ka,mL,  mu,x,y) 

A  is  an  m  x  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
mu  <  n,  and  ka  >  m. 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
When  BVPRD  is  called,  the  product  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  BVPRDl(m,n,  A,ka,mi, mu,x,y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mt  the  number  of- diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,  0  < 
mu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  When 
BVPRD1  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  BTPRD(m,n,  A,  ka,mt,mu,x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mt  <  m,0  < 
mu  <  n,  and  ka  >  m. 

The  argument  x  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  When 
BTPRD  is  called,  the  product  xA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 
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CALL  BTPRDl(m,  n,  A,  ka,  mi,  mu,  x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  then  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mt  <  m,  0  < 
mu  <  n,  and  ka>m. 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  When 
BTPRD1  is  called,  xA+  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 
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PRODUCT  OF  A  COMPLEX  BANDED  MATRIX  AND  VECTOR 

Let  A  be  a  complex  m  X  n  matrix  stored  in  band  form.  Then  the  following  subroutines 
are  available  for  multiplying  A  with  a  complex  vector. 

CALL  CBVPD(m,  n,  A,  ka,mt,mU)x,y) 

A  is  an  m  x  n  matrix  stored  in  band  form,  m*  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  <  m,0  < 

mu  <  n,  and  ka  >  m. 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
A,  x,  y  are  complex  arrays.  When  CBVPD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  CBVPDl(m,  n,  A,  ka,mi,mu,x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  m£  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  mn  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mt  <  m,G  < 
mu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,  x,  y 
are  complex  arrays.  When  CBVPD1  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  CBTPD(m,n,  A,  ka,  m£,mu,  x,y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mt  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  m„  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mj  <  m,0  < 
mu  <  n,  and  ka  >  m. 

The  argument  a:  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  A,  x,  y 
are  complex  arrays.  When  CBTPD  is  called,  xA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 
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CALL  CBTPDl(m,n,  A,  ka,mi,  mu,x,  y) 

A  is  an  m  x  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mt  <  m,0  < 
mu  <  n,  and  ka>m. 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,x,y  are 
complex  arrays.  When  CBTPD1  is  called,  zA  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 
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SOLUTION  OF  BANDED  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 

Let  A  be  a  nonsingular  n  X  n  real  matrix  stored  in  band  form  and  b  a  real  column  vector 
of  dimension  n.  The  subroutine  BSLV  is  available  for  solving  the  system  of  equations  Ax  =  b, 
and  the  subroutine  BSLV1  is  available  for  solving  the  transposed  system  of  equations  Atx  = 
b.  On  an  initial  call  to  either  routine,  partial  pivot  Gauss  elimination  is  first  employed  to 
obtain  an  LU  decomposition  of  A,  and  then  the  equations  are  solved.  BSLV  and  BSLV1 
always  generate  the  same  LU  decomposition  of  A.  After  the  decomposition  is  obtained  on 
an  initial  call  to  BSLV  or  BSLV1,  either  routine  may  be  called  to  solve  a  new  system  of 
equations  Ax  —  r  or  A*x  —  r  without  having  to  redecompose  the  matrix  A. 

CALL  BSLV (MO, A,  ka,  n,  mt,  mu,  X, IWK, IND) 

CALL  BSLVl(MO,A,  ka,  n,  mt,  mu,  X, IWK, IND) 

BSLV  is  called  for  solving  Ax  —  b  and  BSLV1  is  called  for  solving  A* x  =  b.  The 
argument  mt  is  the  number  of  diagonals  below  the  main  diagonal  of  A  containing  nonzero 
elements,  and  mu  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements.  It  is  assumed  that  n  >  1,  0  <  mt  <  n,  and  0  <  mu  <  n.  MO  is  an  input 
argument  which  specifies  if  BSLV  or  BSLV1  is  being  called  for  the  first  time.  On  an  initial 
call,  MO  =  0  and  we  have  the  following  setup: 

A  is  a  2-dimensional  array  of  dimension  kaxm  where  ka  >  n  and  m  >  2m t  +  mu  +  1. 
On  input,  the  first  mj  +  mu  +  1  columns  of  the  array  contain  the  matrix  A  in  band  form. 
When  the  routine  terminates,  the  array  A  will  contain  the  upper  triangular  matrix  U  of 
the  LU  decomposition  and  the  multipliers  which  were  used  to  obtain  it. 

X  is  an  array  of  dimension  n  or  larger.  On  input,  X  contains  the  vector  b.  On  output, 
X  will  contain  the  solution  of  the  system  of  equations. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
indices  involved  in  the  LU  decomposition  are  stored  in  IWK. 

On  an  initial  call  to  BSLV  or  BSLV1,  IND  is  an  integer  variable  that  reports  the  status 
of  the  results.  When  the  routine  terminates,  IND  has  one  of  the  following  values: 

IND  =  0  The  system  of  equations  was  solved. 

IND  =  —  1  Either  n  <  0  or  ka  <  n. 

IND  =  —2  Either  <  0  or  m<  >  n. 

IND  =  —3  Either  mu  <  0  or  mu  >  n. 

IND  =  k  Column  A:  of  A  has  been  reduced  to  a  column  containing  only 
zeros. 

After  an  initial  call  to  BSLV  or  BSLV1,  if  IND  =  0  on  output  then  either  routine  may 
be  called  with  MO  ^  0.  When  MO  ^  0  it  is  assumed  that  only  6  may  have  been  modified. 
BSLV  is  called  for  solving  the  new  set  of  equations  Ax  =  b,  and  BSLV1  is  called  for  solving 
the  new  set  of  equations  Atx  —  b.  The  routine  employs  the  LU  decomposition  obtained  on 
the  initial  call  to  BSLV  or  BSLV1  to  solve  the  new  set  of  equations.  On  input,  X  contains 
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the  new  vector  b.  On  output,  X  will  contain  the  solution  to  the  new  set  of  equations.  In 
this  case,  IND  is  not  referenced  by  the  routine. 

Programming.  BSLV  and  BSLV1  employ  the  subroutines  SNBFA,SNBSL,SAXPY,SSCAL, 
SS  WAP  and  the  functions  ISAMAX  and  SDOT.  SNBFA  and  SNBSL  were  written  by  E.  A. 
Voorhees  (Los  Alamos  Scientific  Laboratory)  and  modified  by  A.  H.  Morris.  The  original 
versions  of  SNBFA  and  SNBSL  are  distributed  by  the  SLATEC  library. 
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SOLUTION  OF  BANDED  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 

Let  A  be  a  nonsingular  n  x  n  complex  matrix  stored  in  band  form  and  b  a  complex 
column  vector  of  dimension  n.  The  subroutine  CBSLV  is  available  for  solving  the  system 
of  equations  Ax  =  b,  and  the  subroutine  CBSLV1  is  available  for  solving  the  transposed 
system  of  equations  A*x  =  6.  On  an  initial  call  to  either  routine,  partial  pivot  Gauss 
elimination  is  first  employed  to  obtain  an  LU  decomposition  of  A,  and  then  the  equations 
are  solved.  CBSLV  and  CBSLV1  always  generate  the  same  LU  decomposition  of  A.  After 
the  decomposition  is  obtained  on  an  initial  call  to  CBSLV  or  CBSLV1,  either  routine  may  be 
called  to  solve  a  new  system  of  equations  Ax  =  r  or  A*x  =  r  without  having  to  redecompose 
the  matrix  A. 

CALL  CBSLV(MO,A,  ka,  n,  mt, mu, X,IWK,IND) 

CALL  CBSLVl(MO,A,  ka,  n,  mt,  mu,  X, IWK, IND) 

CBSLV  is  called  for  solving  Ax  =  b  and  CBSLV  1  is  called  for  solving  Alx  =  b.  The 
argument  mi  is  the  number  of  diagonals  below  the  main  diagonal  of  A  containing  nonzero 
elements,  and  mu  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements.  It  is  assumed  that  n  >  1,  0  <  mt  <  n,  and  0  <  mu  <  n.  MO  is  an  input 
argument  which  specifies  if  CBSLV  or  CBSLV1  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  =  0  and  we  have  the  following  setup: 

A  i3  a  2-dimensional  array  of  dimension  kaxm  where  jfca  >  n  and  m  >  2m*  +  mu  +  1. 
On  input,  the  first  m*  +  mu  +  1  columns  of  the  array  contain  the  matrix  A  in  band  form. 
When  the  routine  terminates,  the  array  A  will  contain  the  upper  triangular  matrix  U  of 
the  LU  decomposition  and  the  multipliers  which  were  used  to  obtain  it. 

X  is  an  array  of  dimension  n  or  larger.  On  input,  X  contains  the  vector  b.  On  output, 
X  will  contain  the  solution  of  the  system  of  equations. 


IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
indices  involved  in  the  LU  decomposition  are  stored  in  IWK. 

On  an  initial  call  to  CBSLV  or  CBSLV1,  IND  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  IND  has  one  of  the  following  values: 
IND  =  0  The  system  of  equations  was  solved. 

IND  =  —  1  Either  n  <  0  or  ka  <  n. 

IND  =  —2  Either  mt  <  0  or  mj  >  n. 

IND  =  -3  Either  mu  <  0  or  m„  >  n. 

IND  =  k  Column  A:  of  A  has  been  reduced  to  a  column  containing  only 
zeros. 


After  an  initial  call  to  CBSLV  or  CBSLV1,  if  IND  =  0  on  output  then  either  routine 
may  be  called  with  MO  ^  0.  When  MO  ^  0  it  is  assumed  that  only  b  may  have  been  mod¬ 
ified.  CBSLV  is  called  for  solving  the  new  set  of  equations  Ax  =  b,  and  CBSLV1  is  called 
for  solving  the  new  set  of  equations  A*x  =  b.  The  routine  employs  the  LU  decomposition 
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obtained  on  the  initial  call  to  CBSLV  or  CBSLV1  to  solve  the  new  set  of  equations.  On 
input,  X  contains  the  new  vector  b.  On  output,  X  will  contain  the  solution  to  the  new  set 
of  equations.  In  this  case,  IND  is  not  referenced  by  the  routine. 

Programming.  CBSLV  and  CBSLV1  employ  the  subroutines  CBFA,  CBSL,  CAXPY, 
CSCAL,  CSWAP  and  the  functions  ICAMAX  and  CDOTU.  CBFA  and  CBSL  are  adapta¬ 
tions  by  A.  H.  Morris  of  the  subroutines  SNBFA  and  SNBSL,  written  by  E.  A.  Voorhees 
(Los  Alamos  Scientific  Laboratory).  SNBFA  and  SNBSL  are  distributed  by  the  SLATEC 
library. 
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STORAGE  OF  SPARSE  MATRICES 


A  matrix  is  said  to  be  sparse  if  it  contains  sufficiently  many  zero  elements  for  it  to 
be  worthwhile  to  use  special  techniques  that  avoid  storing  and  operating  with  the  zeros. 
The  scheme  adopted  by  the  NSWC  library  for  storing  a  sparse  m  x  n  matrix  (atJ)  requires 
three  1-dimensional  arrays  A,  I  A,  J  A.  The  array  A  contains  the  nonzero  elements  of  the 
matrix,  stored  row  by  row.  The  array  J  A  contains  the  column  numbers  of  the  corresponding 
elements  of  the  A  array;  i.e.,  if  A(k)  contains  (atJ)  then  JA(k)  =  j.  The  elements  of  a  row 
of  the  matrix  may  be  given  in  any  order  in  A. 

I A  is  an  array  containing  m+1  integers  which  specify  where  the  rows  of  the  matrix  are 
stored  in  A.  For  *  <  m,  IA{t)  is  the  index  of  the  location  in  A  where  the  ith  row  information 
begins.  It  is  assumed  that  the  rows  are  stored  sequentially;  i.e.,  that  IA(  1)  <  ■  •  •  <  IA(m). 
/A(m+1)  is  set  so  that  IA(m+l)  —  IA(l)  =  the  number  of  elements  stored  in  A.  For  »  <  m, 
if  M(i)  <  IA(i  +  1)  then  A(l)  is  the  first  entry  of  the  tth  row  of  the  matrix  in  A  where 
i  —  /A(s).  Otherwise,  if  JA(t’)  =  IA{i  +  1)  then  no  entries  for  the  ith  row  of  the  matrix  are 
stored  in  A.  This  can  occur  only  if  the  tth  row  of  the  matrix  consists  entirely  of  zeros.  If 
this  occurs  then  the  ith  row  is  called  a  null  row  of  A.  For  any  i  <  m,  IA(t  +  1)  -  IA(i)  is 
the  number  of  entries  for  the  ith  row  of  the  matrix  that  are  stored  in  A.  For  convenience, 
IA(i  +  1)  —  IA{i )  is  called  the  length  of  the  ith  row. 

Example.  The  matrix 

( an  ®12  0  0  0  0  0  aig  > 

0  0  00000  0 
0  0  0  0  0  0  037  Q38 

Vo  0  a43  0  0  0  0  0; 

can  be  stored  as  follows: 


The  storage  of  the  elements  an  an  aig  in  the  order  an  ais  an  is  permissable.  The 
elements  of  a  row  of  the  matrix  may  be  given  in  any  order  desired. 

Remark.  It  is  not  required  that  each  a,y  in  A  be  nonzero. 
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CONVERSION  OF  SPARSE  MATRICES  TO  AND  FROM 
THE  STANDARD  FORMAT 

The  following  subroutines  permit  one  to  convert  sparse  matrices  to  and  from  the  stan¬ 
dard  format. 

CALL  CVRS (A,  ka,  m,n,B,  IB,  JB, NUM, IERR) 

CALL  CVDS(A,  ka,  m,  n,  B,  IB,  JB, NUM, IERR) 

CALL  CVCS(A,  ka,  m,  n,  B,  IB,  JB, NUM, IERR) 

A  is  an  m  X  n  matrix  stored  in  the  standard  format.  The  argument  ka  is  the  number 
of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  A  is  to 
be  stored  in  sparse  form  in  the  arrays  B,  IB,  JB.  CVRS  is  used  if  A  is  a  real  matrix  and 
B  a  real  array,  CVDS  is  used  if  A  is  a  double  precision  matrix  and  B  a  double  precision 
array,  and  CVCS  is  used  if  A  is  a  complex  matrix  and  B  a  complex  array. 

The  input  argument  NUM  is  the  estimated  maximum  number  of  elements  that  will 
appear  in  B  and  JB.  It  is  assumed  that  B  and  JB  are  of  dimension  max{l,NUM}  and 
that  IB  is  of  dimension  m  +  1.  IERR  is  an  integer  variable.  When  the  routine  is  called,  if 
NUM  specifies  sufficient  storage  for  B  and  JB,  then  A  is  stored  in  B,  IB,  JB  and  IERR 
is  assigned  the  value  0. 

Error  Return.  If  it  is  found  that  there  is  not  sufficient  storage  in  B  and  JB  for  the  ith  row 
of  A,  then  IERR  is  set  to  *  and  the  routine  terminates.  In  this  case,  if  t  >  1  then  the  first 
*  -  1  rows  of  A  will  have  been  stored  in  B  and  JB,  and  IB{  1),  . . . ,  IB(i)  will  contain  the 
appropriate  row  locations. 

Remark.  No  zero  elements  of  A  are  stored  in  B,  and  the  elements  of  each  row  of  B  are 
ordered  so  that  the  column  indices  of  the  elements  of  the  row  are  in  ascending  order. 

Example.  If  A  is  the  m  x  n  zero  matrix  then  NUM  can  be  set  to  0.  In  this  case  the  result 
will  be  IB{  1)  =  =  IB(m  +  1)  =  1. 

Note.  It  is  assumed  that  the  storage  areas  A  and  B  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CVSR(A,  IA,J A,  B,  kb,  m,  n) 

CALL  CVSD(A,  IA,J A,  B,  kb,  m,  n) 

CALL  CVSC(A,  I  A,  J  A,  B,  kb,  m,  n) 

A  is  an  m  x  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A,  and  B  is  a  2-dimensional 
array  of  dimension  kb  x  n  where  kb  >  m.  CVSR  is  used  if  A  and  B  are  real  arrays,  CVSD 
is  used  if  A  and  B  are  double  precision  arrays,  and  CVSC  is  used  if  A  and  B  are  complex 
arrays.  When  the  routine  is  called,  the  matrix  A  is  stored  in  the  array  B  in  the  standard 
format. 
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Note.  It  is  assumed  that  the  storage  areas  A  and  B  do  not  overlap. 
Programmer.  A.  H.  Morris. 
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CONVERSION  OF  SPARSE  REAL  MATRICES 
TO  AND  FROM  DOUBLE  PRECISION  FORM 


The  following  subroutines  are  available  for  converting  sparse  real  matrices  to  and  from 
double  precision  form. 

CALL  SCVRD(A,  I  A,  JA,  B,  IB ,  JB,  m) 

A  is  a  sparse  real  matrix  stored  in  the  arrays  A,  I  A,  JA.  A  is  a  real  array  and  B  a 
double  precision  array.  If  A  and  J A  contain  k  elements  then  it  is  assumed  that  B  and  JB 
are  arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows  and  that 
IB  is  an  array  of  dimension  m  +  1.  SCVRD  stores  the  matrix  A  in  double  precision  form 
in  B,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  JA  and  IB,  JB  reference  different  storage  areas. 
Programmer.  A.  H.  Morris. 

CALL  SCVDR(A,  I  A,  JA,  B,  IB,  JB,  m) 

A  is  a  sparse  double  precision  matrix  stored  in  the  arrays  A,  I  A,  J  A.  A  is  a  double 
precision  array  and  B  a  real  array.  If  A  and  JA  contain  k  elements  then  it  is  assumed  that 
B  and  JB  are  arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows 
and  that  IB  is  an  array  of  dimension  m  + 1.  SCVDR  stores  the  matrix  A  in  single  precision 
form  in  B,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  IA,  JA  and  IB,  JB  reference  different  storage  areas. 
Programmer.  A.  H.  Morris. 
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THE  REAL  AND  IMAGINARY  PARTS  OF  A  SPARSE  COMPLEX  MATRIX 


If  A  =  (Aij)  is  a  complex  matrix  then  let  Re(A)  =  (Re(o,y))  and  Im(A)  =  (Im(a,y)) 
denote  the  real  and  imaginary  parts  of  A.  If  the  matrix  A  is  stored  in  sparse  form,  then 
the  following  subroutines  are  available  for  obtaining  Re(A)  and  Im(A)  in  sparse  form. 

CALL  CSREAL (A,IA,JA,B,IB,JB,m) 

A  is  a  sparse  complex  matrix  stored  in  the  arrays  A,  I  A,  J  A.  A  is  a  complex  array 
and  B  a  real  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that  B  and  J  B  are 
arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows  and  that  IB 
is  an  array  of  dimension  m  +  1.  CSREAL  stores  Re(A)  in  sparse  form  in  B,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  Re(A)  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  JA  and  IB,  JB  reference  different  storage  areas. 
Programmer.  A.  H.  Morris. 

CALL  CSIMAG(A,  I  A,  JA,B,  IB,  JB,m) 

A  is  a  sparse  complex  matrix  stored  in  the  arrays  A,  I  A,  JA.  A  is  a  complex  array 
and  B  a  real  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that  B  and  J  B  are 
arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows  and  that  IB 
is  an  array  of  dimension  m  +  1.  CSIMAG  stores  Im(A)  in  sparse  form  in  B,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  Im(A)  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  JA  and  IB,  JB  reference  different  storage  areas. 
Programmer.  A.  H.  Morris. 
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COMPUTING  A  +  B*  FOR  SPARSE  REAL  MATRICES  A  AND  B 


Given  the  real  m  x  n  matrices  A  and  B  stored  in  sparse  form.  Then  the  subroutine 
SCVRC  is  available  for  obtaining  the  complex  matrix  A  +  Bi  where  t  =  y/—i. 

CALL  SCVRC {A,IA,JA,B,IB,JB,C,IC,JC,m,  n , NUM, WK, IERR) 

A  and  B  are  real  m  x  n  matrices  stored  in  the  arrays  A,IA,JA  and  B,IB,JB.  It  is 
assumed  that  A  +  Bi  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC,JC.  A  and  B  are 
real  arrays  and  C  a  complex  array.  NUM  is  the  estimated  maximum  number  of  elements 
that  will  appear  in  C  and  JC.  It  is  assumed  that  C  and  JC  are  arrays  of  dimension 
max{l,NUM}  and  that  IC  is  an  array  of  dimension  m  +  1. 

WK  is  a  real  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  an  integer  variable.  When  SCVRC  is  called,  if  NUM  specifies  sufficient  storage 
for  C  and  JC  then  A  +  Bi  is  stored  in  C,  IC ,  JC.  Also  IERR  is  assigned  the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  kth  row  of  A  +  Bi, 
then  IERR  is  set  to  k  and  the  routine  terminates.  In  this  case,  if  k  >  1  then  the  first  Ar  -  1 
rows  of  A  +  Bi  will  have  been  stored  in  C  and  JC.  Also  iC(l), . . .  ,IC(k)  will  contain  the 
appropriate  row  locations. 

Remark.  No  zeros  are  stored  in  C. 

Programmer.  A.  H.  Morris 
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COPYING  SPARSE  MATRICES 


The  following  subroutines  are  available  for  copying  sparse  matrices. 

CALL  RSCOPY(A, IA,JA,B,IB,JB,m) 

CALL  DSCOPY (A,IA,JA,B,IB,JB,m) 

CALL  CSCOPY (A,IA,JA,B,IB,JB,m) 

RSCOPY  is  used  if  A  and  B  are  real  arrays,  DSCOPY  is  used  if  A  and  B  are  double 
precision  arrays,  and  CSCOPY  is  used  if  A  and  B  are  complex  arrays. 

A  is  a  sparse  matrix  stored  in  the  arrays  A,  IA,JA.  If  A  and  JA  contain  k  elements 
then  it  is  assumed  that  B  and  JB  are  arrays  of  dimension  k.  It  is  also  assumed  that  the 
matrix  A  has  m  >  1  rows  and  that  IB  is  an  array  of  dimension  m  + 1.  The  routine  copies 
the  matrix  A  and  stores  the  copy  in  B,IB,JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  A,  I  A,  JA  and  B,  IB,JB  reference  different  storage 
areas. 

Programmer.  A.  H.  Morris. 
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COMPUTING  CONJUGATES  OF  SPARSE  COMPLEX  MATRICES 


If  A  =  (aij)  is  a  complex  matrix  stored  in  sparse  form,  then  the  following  subroutine 
is  available  for  computing  the  conjugate  matrix  A  =  {aij). 

CALL  SCON  J(A,  I  A,  JA,  B,  IB,  JB,  m) 

It  is  assumed  that  the  sparse  complex  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  If  A 
and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and  JB  are  arrays  of  dimension 
k.  A  and  B  are  complex  arrays.  It  is  assumed  that  the  matrix  A  has  m  >  1  rows  and  that 
IB  is  an  array  of  dimension  m  +  1.  When  the  routine  is  called,  the  conjugate  matrix  A  is 
stored  in  B,  IB,  JB. 

Remark.  The  user  may  let  B  =  A,  IB  =  I  A,  and  JB  =  JA  when  IA(l)  =  1. 

Programmer.  A.  H.  Morris 
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TRANSPOSING  SPARSE  REAL  MATRICES 

The  subroutines  RPOSE  and  RPOSE1  are  available  for  transposing  a  sparse  m  X  n  real 
matrix  A.  RPOSE1  is  more  general  than  RPOSE.  For  any  permutation  n  =  {*1}  ...  ,tm} 
of  {1,  . . .  ,m}  let  P  denote  the  corresponding  m  x  m  permutation  matrix.  Then  RPOSE1 
computes  the  matrix  (PA)4. 

CALL  RPOSE(A,  I  A,  J  A,  B,IB,JB,m,  n) 

It  is  assumed  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  JA.  If  A  and  JA 
contain  k  elements,  then  it  is  also  assumed  that  B  and  J B  are  arrays  of  dimension  k  and 
that  IB  is  an  array  of  dimension  n  +  1.  When  RPOSE  is  called,  the  transpose  A4  is  stored 
in  B,  IB,  JB. 

Remarks.  RPOSE  orders  the  elements  of  each  row  of  A4  so  that  the  column  indices  of  the 
elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero  elements 
in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also  appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  IA,  JA. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 

CALL  RP0SEl(jr,  A,  I  A,  JA,  B,  IB,  JB,m,  n) 

It  is  assumed  that  jt  is  an  integer  array  of  dimension  m  containing  the  data  {»1} 
and  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  IA,  JA.  If  A  and  JA  contain  k 
elements,  then  it  is  also  assumed  that  B  and  J B  are  arrays  of  dimension  k  and  that  IB  is 
an  array  of  dimension  n  +  1.  When  RPOSE1  is  called,  (PA)4  is  computed  and  the  results 
are  stored  in  B,  IB,  JB. 

Remarks.  RPOSE1  orders  the  elements  of  each  row  of  (PA)4  so  that  the  column  indices 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero 
elements  in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also 
appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 
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TRANSPOSING  SPARSE  DOUBLE  PRECISION  MATRICES 


The  subroutines  DPOSE  and  DPOSE1  are  available  for  transposing  a  sparse  m  x  n 
double  precision  matrix  A.  DPOSE1  is  more  general  than  DPOSE.  For  any  permutation 
Jr  =  {«!,  . . .  of  {1,  . . . ,  m}  let  P  denote  the  corresponding  m  x  m  permutation  matrix. 
Then  DPOSE1  computes  the  matrix  (PA)4. 

CALL  DPOSE (A,IA,JA,B,IB,JB,m,n) 

It  is  assumed  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  IA,  JA.  A  and  B 
are  double  precision  arrays.  If  A  and  J A  contain  k  elements,  then  it  is  also  assumed  that 
B  and  JB  are  arrays  of  dimension  k  and  that  IP  is  an  array  of  dimension  n  +  1.  When 
DPOSE  is  called,  the  transpose  At  is  stored  in  B,  IB,  JB. 

Remarks.  DPOSE  orders  the  elements  of  each  row  of  A4  so  that  the  column  indices  of  the 
elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero  elements 
in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also  appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B ,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 

CALL  DPOSEl(x-,  A,  I  A,  JA,  B,  IB,JB,  m,  n) 

It  is  assumed  that  n  is  an  integer  array  of  dimension  m  containing  the  data  {*1}  . . . ,  »'m}, 
and  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  JA.  A  and  B  are  double  precision 
arrays.  If  A  and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and  JB  are  arrays 
of  dimension  k  and  that  IB  is  an  array  of  dimension  n+  1.  When  DPOSE1  is  called,  (PA)4 
is  computed  and  the  results  are  stored  in  B,  IB,  JB. 

Remarks.  DPOSE1  orders  the  elements  of  each  row  of  (PA)4  so  that  the  column  indices 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero 
elements  in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also 
appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  I  A,  JA. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 
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TRANSPOSING  SPARSE  COMPLEX  MATRICES 


The  subroutines  CPOSE  and  CPOSE1  are  available  for  transposing  a  sparse  m  x  n 
complex  matrix  A.  CPOSE1  is  more  general  than  CPOSE.  For  any  permutation  jr  = 
{‘ij  •  •  •  )*m.}  of  {1,  .  ..,m}  let  P  denote  the  corresponding  m  X  m  permutation  matrix. 
Then  CPOSE1  computes  the  matrix  ( PA )4. 

CALL  CPOSE(A,  I  A,  JA,  B,  IB,  JB,  m,  n) 

It  is  assumed  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  JA.  A  and  B 
are  complex  arrays.  If  A  and  J A  contain  k  elements,  then  it  is  also  assumed  that  B  and 
JB  are  arrays  of  dimension  k  and  that  IB  is  an  array  of  dimension  n  +  1.  When  CPOSE 
is  called,  the  transpose  A4  is  stored  in  B,  IB,  JB. 

Remarks.  CPOSE  orders  the  elements  of  each  row  of  A4  so  that  the  column  indices  of  the 
elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero  elements 
in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also  appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  IA,  JA. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 

CALL  CPOSE1  (*-,  A,  I  A,  JA,  B,  IB,  JB,  m,  n) 

It  is  assumed  that  ?r  is  an  integer  array  of  dimension  m  containing  the  data  (jj,  . . . ,  tm}, 
and  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  JA.  A  and  B  are  complex 
arrays.  If  A  and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and  J  B  are  arrays 
of  dimension  k  and  that  IB  is  an  array  of  dimension  n+ 1.  When  CPOSE1  is  called,  (PA)4 
is  computed  and  the  results  are  stored  in  B,  IB,  JB. 

Remarks.  CPOSE1  orders  the  elements  of  each  row  of  (PA)4  so  that  the  column  indices 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero 
elements  in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also 
appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer.  A.  H.  Morris 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 
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ADDITION  OF  SPARSE  MATRICES 


The  following  subroutines  are  available  for  adding  sparse  matrices. 

CALL  SAD  D(A,  I  A,  J  A,  B,  IB,  JB,  C,  IC,  JC,  m,  n  ,NUM ,  WK  ,IERR) 

CALL  DSADD(A,  I  A,  JA,  B,  IB,  JB,C,  IC,  JC,  m,  n, NUM, WK, IERR) 

CALL  CSADD(A,  I  A,  J  A,  B,  IB,  JB,  C,  IC,  JC,  m,  n,NUM,WK,IERR) 

A  and  B  are  sparse  m  x  n  matrices  stored  in  the  arrays  A,IA,JA  and  B,IB,JB.  It 
is  assumed  that  A  +  B  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC,JC.  NUM  is  the 
estimated  maximum  number  of  elements  that  will  appear  in  C  and  JC.  It  is  assumed  that 
C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that  IC  is  an  array  of  dimension 
m  +  1. 

SADD  is  used  if  A,B,C,  and  WK  are  real  arrays,  DSADD  is  used  if  A,B,C,  and  WK 
are  double  precision  arrays,  and  CSADD  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  JC  then  A  +  B  is  computed  and  stored  in  C,IC,JC.  Also  IERR  is 
assigned  the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  ith  row  of  A  +  B,  then 
IERR  is  set  to  *  and  the  routine  terminates.  In  this  case,  if  t  >  1  then  the  first  *  —  1  rows 
of  A  +  B  will  have  been  computed  and  stored  in  C  and  JC.  Also  IC(1),  . . . ,  IC(i)  will 
contain  the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C. 

(2)  It  is  assumed  that  C,IC,JC  reference  different  storage  areas  than  A,IA,JA  and 
B,IB,JB. 

Programmer.  A.  H.  Morris 
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SUBTRACTION  OF  SPARSE  MATRICES 


The  following  subroutines  are  available  for  subtracting  sparse  matrices. 

CALL  SSUBT(A,  I  A,  JA,B,  IB,  JB,  C,  IC,  JC,  m,  n,NUM,WK,IERR) 

CALL  DSSUBT(A,  I  A,  J  A,  B,  IB,  JB,  C ,  IC,  JC,  m,  n, NUM,  WK, IERR) 

CALL  CSSU  BT(A,  I  A,  J  A,  B,  IB,  JB,  C,  IC,  JC,  m,  n, NUM,  WK, IERR) 

A  and  B  are  sparse  m  x  n  matrices  stored  in  the  arrays  A,IA,JA  and  B,IB,JB.  It 
is  assumed  that  A  —  B  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC,JC.  NUM  is  the 
estimated  maximum  number  of  elements  that  will  appear  in  C  and  JC.  It  is  assumed  that 
C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that  IC  is  an  array  of  dimension 
m  +  1. 

SSUBT  is  used  if  A,B,C,  and  WK  are  real  arrays,  DSSUBT  is  used  if  A,B,C,  and  WK 
are  double  precision  arrays,  and  CSSUBT  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  J C  then  A  -  B  is  computed  and  stored  in  C,IC,JC.  Also  IERR  is 
assigned  the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  tth  row  of  A  -  B,  then 
IERR  is  set  to  i  and  the  routine  terminates.  In  this  case,  if  *  >  1  then  the  first  i  -  1  rows  of 
A  —  B  will  have  been  computed  and  stored  in  C  and  JC.  Also  IC(l),  . . . ,  C'(t')  will  contain 
the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C. 

(2)  It  is  assumed  that  C,IC,JC  reference  different  storage  areas  than  A  I A  JA  and 

B,IB,JB.  ’  ' 

Programmer.  A.  H.  Morris 
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MULTIPLICATION  OF  SPARSE  MATRICES 


The  following  subroutines  are  available  for  multiplying  sparse  matrices. 

CALL  SPROD(A,  I  A,  JA,  B,  IB,  JB,  C,  IC,  JC,  t,  m,  n, NUM, WK, IERR) 

CALL  DSPROD(A,  I  A,  JA,  B,  IB,  JB,  C,  IC,  JC,  t,  m,  n,NUM,WK,IERR) 

CALL  CSPROD(  A,  I  A,  JA,  B,  IB,  JB,  C,  IC,  JC,  l,  m,  n, NUM, WK, IERR) 

A  is  a  sparse  Ixm  matrix  stored  in  the  arrays  A,IA,JA,  and  B  a  sparse  m  x  n  matrix 
stored  in  the  arrays  B,  IB,JB.  It  is  assumed  that  AB  is  to  be  stored  in  sparse  form  in  the 
arrays  C,IC,JC.  NUM  is  the  estimated  maximum  number  of  elements  that  will  appear  in 
C  and  JC.  It  is  assumed  that  C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that 
IC  is  an  array  of  dimension  £+1. 

SPROD  is  used  if  A,B,C,  and  WK  are  real  arrays,  DSPROD  is  used  if  A,B,C ,  and  WK 
are  double  precision  arrays,  and  CSPROD  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  JC  then  AB  is  computed  and  stored  in  C,IC,JC.  Also  IERR  is  assigned 
the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  ith  row  of  AB,  then 
IERR  is  set  to  »  and  the  routine  terminates.  In  this  case,  if  *  >  1  then  the  first  i  —  1  rows  of 
AB  will  have  been  computed  and  stored  in  C  and  JC.  Also  JC(1),  . . . ,  IC(t )  will  contain 
the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C. 

(2)  It  is  assumed  that  C,IC,JC  reference  different  storage  areas  than  A,IA,JA  and 
B,  IB,  JB. 

Programmer.  A.  H.  Morris 
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PRODUCT  OF  A  REAL  SPARSE  MATRIX  AND  VECTOR 

Let  A  be  a  real  m  X  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then  the  following 
subroutines  are  available  for  multiplying  A  with  a  real  vector. 

CALL  MVPRD(m,  n,  A,  I  A,  JA,  x,  y) 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
When  MVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  MVPRDl(m,  n,  A,  I  A,  JA,  x,  y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  When 
MVPRD1  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  MTPRD(m,n, A,IA, JA,x,y) 

The  argument  x  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  When 
MTPRD  is  called,  xA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  MTPRDl(m,  n,  A,  IA,  JA,  x,  y) 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  When 
MTPRD1  is  called,  x A  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 
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PRODUCT  OF  A  DOUBLE  PRECISION  SPARSE  MATRIX  AND  VECTOR 

Let  A  be  a  double  precision  m  x  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then 
the  following  subroutines  are  available  for  multiplying  A  with  a  double  precision  vector. 

CALL  DVPRD {m,n,A,  IA,JA,x,y) 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m.  A, 
x,  y  are  double  precision  arrays.  When  DVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 
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CALL  DVPRDl(m,n,A,IA,  JA,x,y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,  x,  y 
are  double  precision  arrays.  When  DVPRD1  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris 

CALL  DTPRD(m,  n,  A,  I  A,  JA,  x,  y) 

The  argument  x  is  a  row  vector  of  dimension  m  and  y  am  array  of  dimension  n.  A,  x, 
y  are  double  precision  arrays.  When  DTPRD  is  called,  x A  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 
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CALL  DTPRD1  (m,n,A,IA,JA,x,y) 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,  x,  y  are 
double  precision  arrays.  When  DTPRD1  is  called,  xA  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 
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PRODUCT  OF  A  COMPLEX  SPARSE  MATRIX  AND  VECTOR 

Let  A  be  a  complex  m  X  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then  the 
following  subroutines  are  available  for  multiplying  A  with  a  complex  vector. 

CALL  CVPRD (m,n,A,IA,JA,x,y) 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
A,  x,y  are  complex  arrays.  When  CVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 
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CALL  CVPRDl(m,  n,  A,  I  A,  J  A,  x,  y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,  x,  y 
are  complex  arrays.  When  CVPRDl  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 
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CALL  CTPRD(m,  n,  A,  JA,  JA,z,  y) 

The  argument  x  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  A,  x,  y 
are  complex  arrays.  When  CTPRD  is  called,  xA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 
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CALL  CTPRDl(m,  n,  A,  I  A,  J  A,  x,  y) 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,  x,  y  are 
complex  arrays.  When  CTPRDl  is  called,  xA  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris 
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ORDERING  THE  ROWS  OF  A  SPARSE  MATRIX 
BY  INCREASING  LENGTH 


Let  A  be  a  sparse  mxn  matrix  stored  in  the  arrays  A,  /A,  J A.  The  following  subroutine 
is  available  for  ordering  the  rows  of  the  matrix  by  increasing  length. 

CALL  SPORD(m,  n,  I  A,  f2,IWK) 

R  is  an  integer  array  of  dimension  m.  When  SPORD  is  called,  the  rows  of  the  matrix 
are  ordered  by  increasing  length.  The  row  ordering  is  given  in  R. 

IWK  is  an  integer  array  of  dimension  m  +  n  + 1  or  larger  that  is  used  for  a  work  space. 

Remark.  If  rows  *1 ,  . ..  ,ik  are  the  rows  of  length  £,  then  the  indices  ils  are  listed  in 

R  in  increasing  sequence. 

Programmer.  A.  H.  Morris 
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REORDERING  SPARSE  MATRICES  INTO  BLOCK  TRIANGULAR  FORM 

Let  A  be  a  sparse  n  x  n  matrix  stored  in  the  arrays  A,  I  A,  JA.  Then  the  subroutine 
BLKORD  is  available  for  reordering  the  rows  and  columns  of  A  so  that  one  has  a  lower 
block  triangular  matrix 
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where  the  blocks  An  are  square  and  cannot  themselves  be  reordered  into  lower  block  trian¬ 
gular  form. 


CALL  BLKORD(n,  I  A,  JA,  R,  C,  IB,  &,IWK,IERR) 

R  and  C  are  integer  arrays  of  dimension  n,  and  IERR  is  an  integer  variable.  When 
BLKORD  is  called,  the  rows  of  the  matrix  are  first  ordered  so  that  the  main  diagonal 
contains  a  maximum  number  of  nonzeros.  After  this  is  done  then  IERR  =  the  number  of 
zeros  that  appear  on  the  diagonal.  If  IERR  =  0  then  the  rows  and  columns  of  the  matrix 
are  ordered  into  block  triangular  form  (*).  The  row  ordering  is  given  in  R  and  the  column 
ordering  is  given  in  C. 

IB  is  an  integer  array  of  dimension  n  and  k  is  an  integer  variable.  When  the  matrix  has 
been  ordered  into  block  triangular  form  (*)  then  k  =  the  number  of  blocks  A„-.  Also  IB(i)  = 
the  row  number  in  the  block  triangular  matrix  of  the  beginning  of  block  An  (t  =  1,  . . . ,  k). 

IWK  is  an  integer  array  of  dimension  5n  or  larger  that  is  used  for  a  work  space  by  the 
routine. 

Error  Return.  If  IERR  ^  0  then  the  routine  terminates.  In  this  case,  R  contains  the  row 
ordering  that  gives  the  main  diagonal  with  the  maximum  number  of  nonzeros. 

Remark.  I  A,  J  A,  and  n  are  not  modified  by  the  routine. 

Programming.  BLKORD  employs  the  subroutines  MC21A,  MC21B,  MC13D,  MC13E  de¬ 
signed  by  I.  S.  Duff  and  J.  K.  Reid  (AERE  Harwell, England). 

References. 

(1)  Duff,  I.  S.,  “On  Algorithms  for  Obtaining  a  Maximum  Transversal,”  ACM  Trans. 
Math  Software  7  (1981),  pp. 315-330. 

(2)  Duff,  I.  S.  and  Reid,  J.  K.,  “An  Implementation  of  Tarjan’s  Algorithm  for  the  Block 
Triangularization  of  a  Matrix,”  ACM  Trans.  Math  Software  4  (1978),  pp.  137-147. 
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SOLUTION  OF  SPARSE  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  x  n  sparse  real  matrix  stored  in  the  arrays  A,IA,JA  and  let  b 
be  a  real  column  vector  of  dimension  n.  The  subroutines  SPSLV  and  RSLV  are  available  for 
solving  the  system  of  equations  Ax  =  b,  and  the  subroutine  TSLV  is  available  for  solving 
the  transposed  system  of  equations  A*x  =  b.  These  routines  employ  partial  pivot  gauss 
elimination  with  column  interchanges  to  first  obtain  an  LU  decomposition  of  A.  If  SPSLV 
is  called  then  only  the  off-diagonal  nonzero  elements  of  U  are  stored,  and  then  the  equations 
are  solved.  However,  if  RSLV  or  TSLV  is  called  then  the  off-diagonal  nonzero  elements  of 
both  L  and  U  are  stored.  Thus  RSLV  and  TSLV  will  frequently  require  at  least  double  the 
amount  of  storage  needed  by  SPSLV,  but  they  can  be  recalled  to  solve  other  systems  of 
equations  Ax  =  r  and  Atx  =  r  without  having  to  redecompose  the  matrix  A.  Moreover, 
since  RSLV  and  TSLV  will  always  generate  the  same  LU  decomposition  of  A,  RSLV  can 
be  called  to  decompose  A  and  solve  a  system  of  equations  Ax  =  b,  and  then  TSLV  can  be 
called  to  solve  a  transposed  system  of  equations  AlX  =  r  using  the  decomposition  obtained 
by  RSLV. 

CALL  SPSLV(n,  A,  I  A,  JA,  b,  R,C,MAX,X,IWK,WK,IERR) 

It  is  assumed  that  n  >  1  and  that  X  is  an  array  of  dimension  n.  The  solution  of  the 
system  of  equations  Ax  =  b  is  computed  and  stored  in  X.  A,IA,  JA  and  b  are  not  modified 
by  the  routine. 

R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  t'i,  . .  ,,in  then  the 
algorithm  first  performs  operations  on  row  tx,  next  on  row  *2>  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  a  subroutine  such  as  SPSLV.  Thus  R  must  be  chosen  judiciously. 
R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  j\,  then  it  is  suggested  that  the 

first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j'2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routine,  and  MAX  is  an  input  argument. 
When  SPSLV  is  called,  an  LU  decomposition  of  A  is  first  obtained  where  U  is  a  unit  upper 
triangular  matrix.  The  off-diagonal  portion  of  U  is  stored  in  sparse  form  in  IWK  and  WK. 
MAX  is  an  estimate  of  the  maximum  number  of  off-diagonal  elements  of  U  that  might  be 
nonzero  and  have  to  be  stored  (MAX  <  n(n  -  l)/2).  IWK  is  an  integer  array  of  dimension 
3 n  +  MAX  +  2  or  larger,  and  WK  is  a  real  array  of  dimension  n  +  MAX  or  larger. 
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IERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  IERR  has  one  of  the  following  values: 

IERR  >  0  Ax  =  b  was  solved.  IERR  =  max{l,m}  where  m  is 

the  number  of  off-diagonal  nonzero  elements  of  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  =  —k  Row  R(k )  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k )  of  A  has  a  duplicate  entry. 

IERR  =  —2 n  —  k  Row  R(k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

IERR  =  —3n  —  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R. 
If  it  is  suspected  that  the  rows  and  columns  of  A  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLKORD  should  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triangular  form  if  one  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  the  rows,,  then  the  row  ordering  given  by  the  subroutine 
SPORD  frequently  yields  good  results.  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothersome  since  partial  pivoting  with  column  interchanges  is  performed. 
The  initial  ordering  C(t’)  =  *  (i  =  1,  . . .  ,n)  always  suffices. 

Programming.  SPSLV  is  a  modification  by  A.  H.  Morris  of  the  subroutine  NSPIV.  SPSLV 
employs  the  subroutine  NSPIV1.  NSPIV  and  NSPIV1  were  written  by  Andrew  H.  Sherman 
(University  of  Texas  at  Austin). 

Reference.  Sherman,  Andrew  H., “Algorithms  for  Sparse  Gaussian  Elimination  with  Partieil 
Pivoting,”  ACM  Trans.  Math  Software  4  (1978),  pp. 330-338. 

CALL  RSLV(M0,n,  A,  JA,  J A,  b,  R, C, MAX, X,IWK,WK, IERR) 

CALL  TSLV(MO,n,  A,  I  A,  JA,  b,  R,  C,  MAX,  X,IWK,WK,  IERR) 

RSLV  is  called  for  solving  Ax  =  b,  and  TSLV  is  called  for  solving  A*x  =  b.  MO  is  am 
input  argument  which  specifies  if  RSLV  or  TSLV  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  =  0  and  we  have  the  following  setup: 

It  is  assumed  that  n  >  1  and  that  X  is  an  array  of  dimension  n.  The  solution  of  the 
system  of  equations  is  stored  in  X.  A,  I  A,  JA  are  not  modified  by  the  routines.  X  and  b 
may  share  the  same  storage  area.  If  A  is  a  separate  storage  area  then  b  is  not  modified  by 
the  routines. 
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R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  t'i,  then  the 

algorithm  first  performs  operations  on  row  t'i,  next  on  row  i2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  RSLV  and  TSLV.  Thus  R  must  be  chosen 
judiciously.  R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  . . .  ,jn  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  jj,  the  second  pivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routines,  and  MAX  is  an  input  ar¬ 
gument.  On  an  initial  call  to  RSLV  or  TSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  and  U  are  stored  in  sparse  form  in  IWK  and  WK.  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  —  1)).  IWK  is  an  integer  array  of  dimension  4 n  +  MAX  +  2  or 
larger,  and  WK  is  a  real  array  of  dimension  2 n  +  MAX  or  larger. 

On  an  initial  call  to  RSLV  or  TSLV,  IERR  is  an  integer  variable  that  reports  the  status 
of  the  results.  When  the  routine  terminates,  IERR  has  one  of  the  following  values: 

IERR  >  0  The  system  of  equations  was  solved.  IERR=max{l,m} 

where  m  is  the  total  number  of  off-diagonal  nonzero 
elements  of  L  and  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  =  —  k  Row  R(k)  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k)  of  A  has  a  duplicate  entry. 

IERR  =  — 2n  —  k  Row  R(k)  of  A  has  been  reduced  to  a  row  containing 
only  zeros. 

IERR  =  —3 n  -  k  Row  k  of  L  or  U  exceeds  storage.  MAX  must  be  in¬ 
creased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

After  an  initial  call  to  RSLV  or  TSLV,  if  IERR  >  0  on  output  then  either  routine  may 
be  called  with  MO  ^  0.  When  MO  0  it  is  assumed  that  only  b  may  have  been  modified. 
RSLV  is  called  for  solving  the  new  set  of  equations  Ax  =  b,  and  TSLV  is  called  for  solving 
the  new  set  of  equations  Atx  =  b.  The  routine  employs  the  LU  decomposition  obtained 
on  the  initial  call  to  RSLV  or  TSLV  to  solve  the  new  system  of  equations.  The  solution  is 
stored  in  X.  As  before,  X  and  b  may  share  the  same  storage  area.  If  MO  ^  0  then  only 
n,  R,  C ,  IWK,  and  WK  are  used.  A,  I  A,  J  A,  MAX,  and  IERR  are  not  referenced  by  the 
routine. 

Note.  The  remarks  concerning  the  ordering  of  the  rows  and  columns  of  A  when  SPSLV  is 
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used  hold  also  for  RSLV  and  TSLV. 

Programming.  RSLV  calls  the  subroutines  RSLV1  and  SPLU,  and  TSLV  calls  the  subrou¬ 
tines  TSLV1  and  SPLU.  These  routines  were  written  by  A.  H.  Morris. 
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DOUBLE  PRECISION  SOLUTION  OF  SPARSE  SYSTEMS 
OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  x  n  sparse  double  precision  matrix  stored  in  the  arrays 
A,IA,JA  and  let  b  be  a  double  precision  column  vector  of  dimension  n.  The  subroutines 
DSPSLV  and  DSLV  are  available  for  solving  the  system  of  equations  Ax  =  b,  and  the 
subroutine  DTSLV  is  available  for  solving  the  transposed  system  of  equations  A*x  =  b. 
These  routines  employ  partial  pivot  Gauss  elimination  with  column  interchanges  to  first 
obtain  an  LU  decomposition  of  A.  If  DSPSLV  is  called  then  only  the  off-diagonal  nonzero 
elements  of  U  are  stored,  and  then  the  equations  are  solved.  However,  if  DSLV  or  DTSLV  is 
called  then  the  off-diagonal  nonzero  elements  of  both  L  and  U  are  stored.  Thus  DSLV  and 
DTSLV  will  frequently  require  at  least  double  the  amount  of  storage  needed  by  DSPSLV,  but 
they  can  be  recalled  to  solve  other  systems  of  equations  Ax  =  r  and  Atx  =  r  without  having 
to  redecompose  the  matrix  A.  Moreover,  since  DSLV  and  DTSLV  will  always  generate  the 
same  LU  decomposition  of  A,  DSLV  can  be  called  to  decompose  A  and  solve  a  system  of 
equations  Ax  =  6,  and  then  DTSLV  can  be  called  to  solve  a  transposed  system  of  equations 
A* x  =  r  using  the  decomposition  obtained  by  DSLV. 

CALL  DSPSLV(n,  A,  I  A,  JA,  b,  R,  C,MAX,X,IWK,WK,IERR) 

A  ,  b,  and  X  are  double  precision  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an 
array  of  dimension  n.  The  solution  of  the  system  of  equations  Ax  =  b  is  computed  and 
stored  in  X.  A, I  A,  JA  and  b  are  not  modified  by  the  routine. 

R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  t'i,  ...  ,«n  then  the 
algorithm  first  performs  operations  on  row  t’i,  next  on  row  »2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on  the 
overall  performance  of  a  subroutine  such  as  DSPSLV.  Thus  R  must  be  chosen  judiciously. 
R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  j\,  then  it  is  suggested  that  the 

first  pivot  element  may  be  from  column  jj,  the  second  pivot  element  from  column  J2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routine,  and  MAX  is  an  input  argument. 
When  DSPSLV  is  called,  an  LU  decomposition  of  A  is  first  obtained  where  U  is  a  unit  upper 
triangular  matrix.  The  off-diagonal  portion  of  U  is  stored  in  sparse  form  in  IWK  and  WK. 
MAX  is  an  estimate  of  the  maximum  number  of  off-diagonal  elements  of  U  that  might  be 
nonzero  and  have  to  be  stored  (MAX  <  n(n  -  l)/2).  IWK  is  an  integer  array  of  dimension 
3m  +  MAX  +  2  or  larger,  and  WK  is  a  double  precision  array  of  dimension  n  +  MAX  or 
larger. 
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IERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  IERR  has  one  of  the  following  values: 

IERR  >  0  Ax  =  b  was  solved.  IERR  =  max{l,m}  where  m  is 

the  number  of  olf-diagonal  nonzero  elements  of  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  =  —k  Row  R(k )  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k)  of  A  has  a  duplicate  entry. 

IERR  =  —2 n  —  k  Row  R(k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

IERR  =  — 3n  —  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R. 
If  it  is  suspected  that  the  rows  and  columns  of  A  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLKORD  should  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triangular  form  if  one  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  the  rows,  then  the  row  ordering  given  by  the  subroutine 
SPORD  frequently  yields  good  results.  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothersome  since  partial  pivoting  with  column  interchanges  is  performed. 
The  initial  ordering  C(t)  =  t  (*  =  1;  . . . ,  n)  always  suffices. 

Programming.  DSPSLV  an  adaptation  by  A.  H.  Morris  of  the  subroutine  NSPIV  written 
by  Andrew  H.  Sherman  (University  of  Texas  at  Austin).  DSPSLV  employs  the  subroutine 
DNSPIV. 

Reference.  Sherman,  Andrew  H., “Algorithms  for  Sparse  Gaussian  Elimination  with  Partial 
Pivoting,”  ACM  Trans.  Math  So  ftware  4  (1978),  pp. 330-338. 

CALL  DSLV(MO,n,  A,  I  A,  JA,  b,  R,  C,  MAX,  X,IWK,WK,  IERR) 

CALL  DTSLV(M0,n,  A,  I  A,  JA,  b,  R,  C,  MAX,  X,IWK,WK,  IERR) 

DSLV  is  called  for  solving  Ax  —  b,  and  DTSLV  is  called  for  solving  Atx  =  b.  MO  is  an 
input  argument  which  specifies  if  DSLV  or  DTSLV  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  =  0  and  we  have  the  following  setup: 

A,  b,  and  X  are  double  precision  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an 
array  of  dimension  n.  The  solution  of  the  system  of  equations  is  stored  in  X.  A,  I  A,  JA  are 
not  modified  by  the  routines.  X  and  b  may  share  the  same  storage  area.  If  X  is  a  separate 
storage  area  then  b  is  not  modified  by  the  routines. 
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R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  $1}  .  ..,*n  then  the 
algorithm  first  performs  operations  on  row  »'i,  next  on  row  t2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  DSLV  and  DTSLV.  Thus  R  must  be  chosen 
judiciously.  R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  jj,  ...  ,jn  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routines,  and  MAX  is  an  input  argu¬ 
ment.  On  an  initial  call  to  DSLV  or  DTSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  and  U  are  stored  in  sparse  form  in  IWK  and  WK.  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  —  1)).  IWK  is  an  integer  array  of  dimension  4 n  +  MAX  +  2  or 
larger,  and  WK  is  a  double  precision  array  of  dimension  2 n  +  MAX  or  larger. 

On  an  initial  call  to  DSLV  or  DTSLV,  IERR  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  IERR  has  one  of  the  following  values: 

IERR  >0  The  system  of  .equations  was  solved.  EERR=max{l,m} 
where  m  is  the  total  number  of  off-diagonal  nonzero 
elements  of  L  and  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  =  —k  Row  R{k)  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k)  of  A  has  a  duplicate  entry. 

IERR  =  — 2n  —  k  Row  R(k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

IERR  =  -in  —  k  Row  k  of  L  or  U  exceeds  storage.  MAX  must  be  in¬ 
creased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

After  an  initial  call  to  DSLV  or  DTSLV,  if  IERR  >  0  on  output  then  either  routine  may 
be  called  with  MO  y^  0.  When  MO  y^  0  it  is  assumed  that  only  b  may  have  been  modified. 
DSLV  is  called  for  solving  the  new  set  of  equations  Ax  —  b,  and  DTSLV  is  called  for  solving 
the  new  set  of  equations  Atx  =  b.  The  routine  employs  the  LU  decomposition  obtained  on 
the  initial  call  to  DSLV  or  DTSLV  to  solve  the  new  system  of  equations.  The  solution  is 
stored  in  X.  As  before,  X  and  b  may  share  the  same  storage  area.  If  MO  yt  0  then  only 
n,  R,  C,  IWK,  and  WK  are  used.  A,  I  A,  J  A,  MAX,  and  IERR  are  not  referenced  by  the 
routine. 

Note.  The  remarks  concerning  the  ordering  of  the  rows  and  columns  of  A  when  DSPSLV 
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is  used  hold  also  for  DSLV  and  DTSLV. 

Programming.  DSLV  calls  the  subroutines  DSLV1  and  DSPLU,  and  DTSLV  calls  the 
subroutines  DTSLV1  and  DSPLU.  These  routines  were  written  by  A.  H.  Morris. 
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SOLUTION  OF  SPARSE  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  x  n  sparse  complex  matrix  stored  in  the  arrays  A ,  I  A,  JA  and 
let  b  be  a  complex  column  vector  of  dimension  n.  The  subroutines  CSPSLV  and  CSLV  are 
available  for  solving  the  system  of  equations  Ax  =  b,  and  the  subroutine  CTSLV  is  available 
for  solving  the  transposed  system  of  equations  Atx  =  b.  These  routines  employ  partial  pivot 
Gauss  elimination  with  column  interchanges  to  first  obtain  an  LU  decomposition  of  A.  If 
CSPSLV  is  called  then  only  the  off-diagonal  nonzero  elements  of  U  are  stored,  and  then  the 
equations  are  solved.  However,  if  CSLV  or  CTSLV  is  called  then  the  off-diagonal  nonzero 
elements  of  both  L  and  U  are  stored.  Thus  CSLV  and  CTSLV  will  frequently  require  at 
least  double  the  amount  of  storage  needed  by  CSPSLV,  but  they  can  be  recalled  to  solve 
other  systems  of  equations  Ax  =  r  and  Atx  =  r  without  having  to  redecompose  the  matrix 
A.  Moreover,  since  CSLV  and  CTSLV  will  always  generate,  the  same  LU  decomposition 
of  A,  CSLV  can  be  called  to  decompose  A  and  solve  a  system  of  equations  Ax  =  b,  and 
then  CTSLV  can  be  called  to  solve  a  transposed  system  of  equations  A*x  —  r  using  the 
decomposition  obtained  by  CSLV. 

CALL  CSPSLV(n,  A,  I  A,  JA,  b ,  R,  C,MAX,X,IWK,WK,IERR) 

A  ,  b,  and  X  are  complex  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an  array  of 
dimension  n.  The  solution  of  the  system  of  equations  Ax  =  b  is  computed  and  stored  in  X. 
A, I  A,  J  A  and  b  are  not  modified  by  the  routine. 

R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  t'x,  ...,!„  then  the 
algorithm  first  performs  operations  on  row  »i,  next  on  row  t'2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on  the 
overall  performance  of  a  subroutine  such  as  CSPSLV.  Thus  R  must  be  chosen  judiciously. 
R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  j\,  . . .  ,jn  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j'2,  etc. 
However,  since  partied  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  6. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routine,  and  MAX  is  an  input  argument. 
When  CSPSLV  is  called,  an  LU  decomposition  of  A  is  first  obtained  where  U  is  a  unit  upper 
triangular  matrix.  The  off-diagonal  portion  of  U  is  stored  in  sparse  form  in  IWK  and  WK. 
MAX  is  an  estimate  of  the  maximum  number  of  off-diagonal  elements  of  U  that  might  be 
nonzero  and  have  to  be  stored  (MAX  <  n(n  —  l)/2).  IWK  is  an  integer  array  of  dimension 
3n  +  MAX  +  2  or  larger,  and  WK  is  a  complex  array  of  dimension  n  +  MAX  or  larger. 
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IERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  IERR  has  one  of  the  following  values: 

IERR  >  0  Ax  =  b  was  solved.  IERR  =  max{l,m}  where  m  is 

the  number  of  off-diagonal  nonzero  elements  of  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  —  —k  Row  R(k )  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k)  of  A  has  a  duplicate  entry. 

IERR  =  —2 n  —  k  Row  R(k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

IERR  =  —3 n  —  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R. 
If  it  is  suspected  that  the  rows  and  columns  of  A  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLKORD  should  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triangular  form  if  one  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  the  rows,  then  the  row  ordering  given  by  the  subroutine 
SPORD  frequently  yields  good  results.  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothersome  since  partial  pivoting  with  column  interchanges  is  performed. 
The  initial  ordering  C(t)  =  i  (1  =  1,  . . . ,  n)  always  suffices. 

Programming.  CSPSLV  is  an  adaptation  by  A.  H.  Morris  of  the  subroutine  NSPIV  written 
by  Andrew  H.  Sherman  (University  of  Texas  at  Austin).  CSPSLV  employs  the  subroutine 
CNSPIV. 

Reference.  Sherman,  Andrew  H., “Algorithms  for  Sparse  Gaussian  Elimination  with  Partial 
Pivoting,”  ACM  Trans.  Math  Software  4  (1978),  pp. 330-338. 

CALL  CSLV(MO,  n,  A,  I  A,  J  A,  b,  R,  C,  MAX,  X,IWK,WK,  IERR) 

CALL  CTSLV(MO,n,A,/A,  JA,  6,  i?,C, MAX, X,IWK,WK, IERR) 

CSLV  is  called  for  solving  Ax  =  i>,  and  CTSLV  is  called  for  solving  Atx  =  b.  MO  is  an 
input  argument  which  specifies  if  CSLV  or  CTSLV  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  =  0  and  we  have  the  following  setup: 

A,  b,  and  X  are  complex  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an  array  of 
dimension  n.  The  solution  of  the  system  of  equations  is  stored  in  X.  A,  I  A,  J  A  are  not 
modified  by  the  routines.  X  and  b  may  share  the  same  storage  area.  If  X  is  a  separate 
storage  area  then  b  is  not  modified  by  the  routines. 
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R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  sure 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  »i,  then  the 

algorithm  first  performs  operations  on  row  t'i,  next  on  row  »2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  CSLV  and  CTSLV.  Thus  R  must  be  chosen 
judiciously.  R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  ji,  ...  ,jn  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routines,  and  MAX  is  an  input  argu¬ 
ment.  On  an  initial  call  to  CSLV  or  CTSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  and  U  are  stored  in  sparse  form  in  IWK  and  WK.  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  —  1)).  IWK  is  an  integer  array  of  dimension  4 n  +  MAX  +  2  or 
larger,  and  WK  is  a  complex  array  of  dimension  2 n  +  MAX  or  larger. 

On  an  initial  call  to  CSLV  or  CTSLV,  IERR  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  IERR  has  one  of  the  following  values: 

IERR  >  0  The  system  of  equations  was  solved.  IERR=max{l,  m) 

where  m  is  the  total  number  of  off-diagonal  nonzero 
elements  of  L  and  U. 

IERR  =  0  The  argument  n  is  nonpositive. 

IERR  =  —  k  Row  f2(&)  of  A  is  null. 

IERR  =  —  n  —  k  Row  R(k )  of  A  has  a  duplicate  entry. 

IERR  =  —2 n  —  k  Row  R{k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

IERR  =  -3 n  —  k  Row  k  of  L  or  U  exceeds  storage.  MAX  must  be  in¬ 
creased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

After  an  initial  call  to  CSLV  or  CTSLV,  if  IERR  >  0  on  output  then  either  routine  may 
be  called  with  MO  yt  0.  When  MO  0  it  is  assumed  that  only  b  may  have  been  modified. 
CSLV  is  called  for  solving  the  new  set  of  equations  Aa:  =  6,  and  CTSLV  is  called  for  solving 
the  new  set  of  equations  Atx  =  b.  The  routine  employs  the  LU  decomposition  obtained  on 
the  initial  call  to  CSLV  or  CTSLV  to  solve  the  new  system  of  equations.  The  solution  is 
stored  in  X.  As  before,  X  and  b  may  share  the  same  storage  area.  If  MO  0  then  only 
n,  R,  C ,  IWK,  and  WK  are  used.  A,  I  A,  JA,  MAX,  and  IERR  are  not  referenced  by  the 
routine. 
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Note.  The  remarks  concerning  the  ordering  of  the  rows  and  columns  of  A  when  CSPSLV 
is  used  hold  also  for  CSLV  and  CTSLV. 

Programming.  CSLV  calls  the  subroutines  GSLV1  and  CSPLU,  and  CTSLV  calls  the 
subroutines  CTSLV1  and  CSPLU.  These  routines  were  written  by  A.  H.  Morris. 
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COMPUTATION  OF  EIGENVALUES  OF  GENERAL  REAL  MATRICES 


The  subroutines  EIG  and  EIG1  are  available  for  computing  the  eigenvalues  of  real 
matrices.  These  routines  frequently  yield  results  accurate  to  13-14  significant  digits.  Indeed, 
for  symmetric  matrices  they  may  give  2  or  more  digits  better  accuracy  than  the  routines 
designed  specifically  for  symmetric  matrices.  However,  if  the  eigenvalues  are  not  distinct  or 
if  they  are  exceedingly  tightly  clustered,  then  a  severe  drop  in  accuracy  can  occur  when  the 
matrix  is  not  symmetric.  In  this  case  one  should  not  expect  more  than  7-8  digit  accuracy. 

CALL  EIG(IBAL,A,  ka,  n,  WR,  W/,IERR) 

CALL  EIG1(IBAL,A,  ka,  n,  WR,  W/,IERR) 

A  is  a  matrix  of  order  n  >  1  and  WR,WI  are  real  arrays  of  dimension  n  or  larger. 
When  EIG  or  EIG1  is  called  then  the  eigenvalues  Ai,  . . . ,  A„  of  A  are  computed.  The  real 
parts  of  the  eigenvalues  are  stored  in  WR(  1),  ; . . ,  WR(n)  and  the  imaginary  parts  are  stored 
in  . . . ,  WI(n).  The  eigenvalues  are  unordered  except  that  complex  conjugate  pairs 

of  eigenvalues  appear  consecutively  with  the  eigenvalue  having  the  positive  imaginary  part 
being  first. 

IBAL  and  ka  are  input  arguments.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in,  the  calling  program.  IBAL  may  be  any  integer.  If  IBAL  ^  0 
then  the  routines  balance  A  before  they  compute  the  eigenvalues.  Otherwise,  if  IBAL  =  0 
then  A  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  IERR  is  set 
to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the  jtK  eigenvalue  Ay, 
then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then  the  eigenvalues 
Ay+i,  . . . ,  An  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  in  a  slight  loss  of  accuracy.  On  the  other 
hand,  balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the 
accuracy  by  as  much  as  5-6  significant  digits.  Thus  it  is  recommended  that  balancing 
be  done. 

(2)  A  is  destroyed  during  computation.  EIG  and  EIG1  reduce  A  to  upper  Hessenberg 
form  and  then  apply  the  QR  algorithm  to  obtain  the  eigenvalues.  They  differ  only 
in  the  choice  of  transformations  used  to  reduce  A  to  upper  Hessenberg  form.  EIG 
employs  elementary  similarity  transformations  and  EIG1  employs  orthogonal  similarity 
transformations.  In  theory  the  use  of  orthogonal  transformations  assures  one  of  a 
tighter  bound  on  the  errors.  However,  since  in  practice  matrices  infrequently  arise 
for  which  the  orthogonal  transformations  actually  generate  more  accurate  results,  and 
since  the  orthogonal  transformations  normally  require  more  time  than  the  elementary 
transformations,  therefore  EIG  is  the  recommended  routine. 
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Programming.  EIG  and  EIG1  axe  driver  routines  for  the  EISPACK  subroutines  BALANC, 
ELMHSO,  ORTHES,  and  HQR.  These  subroutines  were  developed  at  Argonne  National 
Laboratory.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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COMPUTATION  OF  EIGENVALUES  AND  EIGENVECTORS  OF 
GENERAL  REAL  MATRICES 


The  subroutines  EIGV  and  EIGV1  are  available  for  computing  the  eigenvalues  and 
eigenvectors  of  real  matrices.  These  routines  are  extensions  of  the  respective  eigenvalue 
routines  EIG  and  EIG1.  Thus  all  comments  made  concerning  the  accuracy  of  the  eigenvalues 
produced  by  EIG  and  EIG1  apply  also  to  EIGV  and  EIGV1.  In  particular,  EIGV  and 
EIG VI  can  frequently  yield  high  precision  results  for  the  eigenvalues  if  they  are  distinct. 
However,  be  aware  that  errors  in  the  eigenvalues,  no  matter  how  seemingly  insignificant, 
can  be  considerably  magnified  in  the  computation  of  the  eigenvectors.  It  is  not  at  all 
unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the  eigenvalue  is  correct  to  within 
2-3  units  of  the  14th  significant  digit,  but  the  components  of  the  corresponding  eigenvector 
are  only  accurate  to  9-10  significant  digits.  In  the  case  of  repeated  eigenvalues  the  situation 
regarding  the  eigenvectors  is  totally  unpredictable.  The  components  of  such  an  eigenvector 
may  be  correct  to  6-7  significant  digits,  or  the  eigenvector  may  not  even  be  an  eigenvector! 
In  this  case  the  results  should  be  checked. 

CALL  EIGV(IBAL,  A,  ka,  n,  WR,WI,ZR,ZI,IERR) 

CALL  EIGV1  (IBAL,  A,  ka,  n,  WR, WI,ZR,ZI,IERR) 

A  is  a  matrix  of  order  n  >  1  and  WR,  WI  are  real  arrays  of  dimension  n  or  larger. 
When  EIGV  or  EIGV1  is  called  the  eigenvalues  Ai,  . . . ,  and  corresponding  eigenvectors 
z\ ,  . . . ,  zn  are  computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(l),  . . .  ,WR(n) 
and  the  imaginary  parts  are  stored  in  WI(1),  ...,WI(n).  The  eigenvalues  are  unordered 
except  that  complex  conjugate  pairs  of  eigenvalues  appear  consecutively  with  the  eigenvalue 
having  the  positive  imaginary  part  being  first. 

The  input  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in 
the  calling  program.  ZR  and  ZI  are  real  arrays  of  dimension  ka  X  n.  For  j  =  1,  . . . ,  n  the 
real  parts  of  the  components  of  the  eigenvector  Zj  are  stored  in  the  jth  column  of  ZR  (in 
locations  ZR(1  J),  . . .  ,ZR (n,j))  and  the  imaginary  parts  are  stored  in  the  jth  column  of  ZI. 
The  eigenvectors  z\,  . . .  ,zn  are  not  normalized. 

IBAL  is  an  input  argument  that  can  be  assigned  any  integer  value.  If  IBAL  ^  0  then 
the  routines  balance  A  before  they  compute  the  eigenvalues  and  eigenvectors.  Otherwise, 
if  IBAL  =  0  then  A  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are  found 
then  IERR  is  set  to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the 
eigenvalue  Ay,  then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then 
the  eigenvalues  Xj+i,  . . . ,  An  will  have  been  computed  and  the  results  stored  in  the  WR  and 
WI  arrays.  However,  none  of  the  eigenvectors  will  have  been  computed.  The  eigenvectors 
are  computed  only  after  all  the  eigenvalues  have  been  obtained. 
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Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  in  a  slight  loss  of  accuracy.  On  the  other  hand, 
balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the  accuracy 
of  the  eigenvalues  by  as  much  as  5-6  significant  digits.  When  this  occurs  balancing 
will  normally  be  needed  to  obtain  the  eigenvectors.  In  general,  it  is  recommended  that 
balancing  be  done. 

(2)  A  is  destroyed  during  computation.  EIGV  and  EIGV1  both  reduce  A  to  upper  Hes- 
senberg  form,  apply  the  QR  algorithm  to  the  Hessenberg  matrix  to  obtain  the  eigen¬ 
values,  and  then  backsubstitute  to  generate  the  eigenvectors.  They  differ  only  in  the 
choice  of  transformations  used  to  reduce  A  to  upper  Hessenberg  form.  EIGV  employs 
elementary  similarity  transformations  and  EIGV1  employs  orthogonal  similarity  trans¬ 
formations.  In  theory  the  use  of  orthogonal  transformations  assures  one  of  a  tighter 
bound  on  the  errors.  However,  since  in  practice  matrices  infrequently  arise  for  which 
the  orthogonal  transformations  actually  generate  more  accurate  results,  and  since  the 
orthogonal  transformations  normally  require  more  time  than  the  elementary  transfor¬ 
mations,  therefore  EIGV  is  the  recommended  routine. 

Programming.  EIGV  and  EIGV1  are  driver  routines  for  the  EISPACK  subroutines  BAL- 
ANC,  ELMHSO,  ORTHES,  ELTRNO,  ORTRAN,  HQR2,  and  BALBAK.  These  subroutines 
were  developed  at  Argonne  National  Laboratory.  The  functions  SPMPAR  and  IPMPAR 
are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  OF 

REAL  MATRICES 

The  subroutine  DEIG  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  of  real  matrices.  This  routine  frequently  yields  results  accurate  to  26-28  significant 
digits.  However,  if  the  eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly  clus¬ 
tered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one  should  not  expect  more 
than  13-14  digit  accuracy. 

CALL  DEIG(IBAL,  A,  ka,  n,  WR,WI,IERR) 

A  is  a  double  precision  matrix  of  order  n  >  1  and  WR,  WI  are  double  precision  arrays 
of  dimension  n  or  larger.  When  DEIG  is  called  then  the  eigenvalues  Ai,  . . . ,  A„  of  A  are 
computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(l),  ...,WR(n)  and  the 
imaginary  parts  are  stored  in  WI(1),  . . .  ,WI(n).  The  eigenvalues  are  unordered  except  that 
complex  conjugate  pairs  of  eigenvalues  appear  consecutively  with  the  eigenvalue  having  the 
positive  imaginary  part  being  first. 

IBAL  and  ka  are  input  arguments.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  IBAL  may  be  any  integer.  If  IBAL  ^ 
0  then  the  routine  balances  A  before  it  computes  the  eigenvalues.  Otherwise,  if  IBAL  =  0 
then  A  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  IERR  is  set 
to  0.  Otherwise,  if  more  than  50  iterations  are  required  to  compute  the  jth  eigenvalue  A j, 
then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then  the  eigenvalues 
Ay+i,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  A  is  destroyed  during  computation. 

(2)  DEIG  is  a  double  precision  version  of  the  eigenvalue  routine  EIG1. 

Programming.  DEIG  is  a  driver  routine  for  the  subroutines  DBAL,  DORTH,  and  DHQR. 
These  subroutines  are  double  precision  versions  of  the  EISPACK  subroutines  BALANC, 
ORTHES,  and  HQR,  developed  at  Argonne  National  Laboratory.  The  double  precision 
versions  were  prepared  by  A.  H.  Morris.  The  functions  DPMPAR  and  IPMPAR  are  also 
used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al..  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  AND 
EIGENVECTORS  OF  REAL  MATRICES 


The  subroutine  DEIGV  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  and  eigenvectors  of  real  matrices.  This  routine  frequently  yields  values  for  the  eigen¬ 
values  that  are  accurate  to  26-28  significant  digits.  However,  be  aware  that  errors  in  the 
eigenvalues,  no  matter  how  seemingly  insignificant,  can  be  considerably  magnified  in  the 
computation  of  the  eigenvectors.  If  the  eigenvalues  are  not  distinct  or  if  they  are  exceed¬ 
ingly  tightly  clustered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one  should 
not  expect  the  eigenvalues  to  have  more  than  13-14  digit  accuracy. 

CALL  DEIGV(IBAL,  A,  ka,  n,  WR,WI,ZR,ZI,IERR) 

A  is  a  double  precision  matrix  of  order  n  >  1  and  WR,  WI  are  double  precision 
arrays  of  dimension  n  or  larger.  When  DEIGV  is  called  then  the  eigenvalues  Aj.,  . ,.,An 
and  corresponding  eigenvectors  z\ ,  . . . ,  zn  are  computed.  The  real  parts  of  the  eigenvalues 
are  stored  in  WR(1),  . . .  ,WR(n)  and  the  imaginary  parts  are  stored  in  WI(l),  . . .  ,WI(n). 
The  eigenvalues  are  unordered  except  that  complex  conjugate  pairs  of  eigenvalues  appear 
consecutively  with  the  eigenvalue  having  the  positive  imaginary  part  being  first. 

The  input  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in 
the  calling  program.  ZR  and  ZI  are  double  precision  arrays  of  dimension  ka  x  n.  For 
j  =  1,  . . . ,  n  the  real  parts  of  the  components  of  the  eigenvector  z}-  are  stored  in  the  jth 
column  of  ZR  (in  locations  ZR(1  J),  . . .  ,ZR(n,  j))  and  the  imaginary  parts  are  stored  in  the 
ith  column  of  ZI.  The  eigenvectors  z\ ,  . . .  ,zn  are  not  normalized. 

IBAL  is  an  input  argument  that  can  be  assigned  any  integer  value.  If  IBAL  yt  0  then 
the  routine  balances  A  before  it  computes  the  eigenvalues  and  eigenvectors.  Otherwise,  if 
IBAL  =  0  then  A  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are  found 
then  IERR  is  set  to  0.  Otherwise,  if  more  than  50  iterations  are  required  to  compute  the  jth 
eigenvalue  Ay,  then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then 
the  eigenvalues  A J+1,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and 
WI  arrays.  However,  none  of  the  eigenvectors  will  have  been  computed.  The  eigenvectors 
are  computed  only  after  all  the  eigenvalues  have  been  obtained. 

Remarks. 

(1)  A  is  destroyed  during  computation. 

(2)  DEIGV  is  a  double  precision  version  of  the  eigenvalue/eigenvector  routine  EIGV1. 
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Programming.  DEIGV  is  a  driver  routine  for  the  subroutines  DBAL,  DORTH,  DORTRN, 
DHQR2,  sind  DBABK.  These  subroutines  are  double  precision  versions  of  the  EISPACK 
routines  BALANC,  ORTHES,  ORTRAN,  HQR2,  and  BALBAK,  developed  at  Argonne 
National  Laboratory.  The  double  precision  versions  were  prepared  by  A.  H.  Morris.  The 
functions  DPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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COMPUTATION  OF  EIGENVALUES  OF  SYMMETRIC  REAL  MATRICES 


The  subroutines  SEIG  and  SEIG1  are  available  for  computing  the  eigenvalues  of  sym¬ 
metric  real  matrices.  These  routines  frequently  yield  high  precision  results.  SEIG  is  faster 
than  SEIG1,  but  at  times  SEIG1  will  produce  better  results  when  the  symmetric  matrix  is 
tridiagonal.  For  arbitrary  symmetric  matrices  it  is  not  clear  if  there  is  any  difference  in  the 
reliability  of  the  routines. 

CALL  SE!G(A,  ka,  n,  W,  T,  IERR) 

CALL  SEIG1(A,  ka,  n,  W,  T,  IERR) 

A  is  a  symmetric  matrix  of  order  n  >  1  and  W  an  array  of  dimension  n  or  larger. 
When  SEIG  or  SEIG1  is  called  the  eigenvalues  Ax,  . . . ,  An  are  computed  and  stored  in 
W(l),  ..  .  ,W(n).  The  eigenvalues  are  ordered  so  that  Ax  <  •*•  <  A„. 

A  may  be  packed  or  in  standard  form.1  The  input  argument  ka  is  a  nonnegative 
integer.  If  ka  =  0  then  A  is  assumed  to  be  packed.  Otherwise,  if  ka  0  then  A  is  assumed 
to  be  in  the  standard  format.  Iq  this  case  ka  has  the  value: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  n.  However,  it  is  not  required  that  A(i,j)  be  defined  for  i  <  j. 
Only  the  lower  triangular  elements  of  A  are  used. 

T  is  an  array  used  for  temporary  storage.  If  SEIG  is  called  then  T  must  be  of  dimension 
2 n.  However,  if  SEIG1  is  called  then  T  need  only  be  of  dimension  n. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  IERR  is 
set  to  0.  Otherwise,  if  more  than  30  iterations  of  the  QL  algorithm  are  required  to  compute 
the  j**1  eigenvalue  Ay,  then  IERR  is  set  to  j .  In  this  case,  if  j  >  1  then  the  eigenvalues 
Ax,  ...,Ay_i  will  have  been  computed  and  stored  in  W.  The  eigenvalues  are  ordered  so 
that  Ai  <  ••■  <  Ay_ j .  However,  they  need  not  be  the  smallest  eigenvalues  of  A. 

Note.  A  is  destroyed  during  computation. 

Programming.  SEIG  and  SEIG1  are  driver  routines  for  the  EISPACK  subroutines  TRED1, 
TRED3,  TQLRAT,  and  IMTQL1.  These  subroutines  were  developed  at  Argonne  National 
Laboratory.  The  function  SPMPAR  is  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


1  For  details  on  the  packed  format  see  the  section  on  packing  and  unpacking  symmetric  matrices. 


309 


COMPUTATION  OF  EIGENVALUES  AND  EIGENVECTORS  OF 
SYMMETRIC  REAL  MATRICES 


The  subroutines  SEIGV  and  SEIGV1  are  available  for  computing  the  eigenvalues  and 
eigenvectors  of  symmetric  real  matrices.  These  routines  frequently  yield  high  precision  re¬ 
sults  for  the  eigenvalues.  However,  be  aware  that  errors  in  the  eigenvalues,  no  matter  how 
seemingly  insignificant,  can  be  considerably  magnified  in  the  computation  of  the  eigenvec¬ 
tors.  It  is  not  at  all  unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the  eigenvalue 
is  correct  to  within  2-3  units  of  the  14th  significant  digit,  but  the  components  of  the  cor¬ 
responding  eigenvector  are  only  accurate  to  9-10  significant  digits.  SEIGV  is  faster  than 
SEIGV1,  but  at  times  SEIGV1  will  produce  better  results  when  the  symmetric  matrix  is 
tridiagonal.  For  arbitrary  symmetric  matrices  it  is  not  clear  if  there  is  any  difference  in  the 
reliability  of  the  routines. 

CALL  SEIGV(A,  ka,  n,  IV,  Z,  T,  IERR) 

CALL  SElGVl (A,ka,  n,W,  2, T,  IERR) 

A  is  a  symmetric  matrix  of  order  n  >  1  and  W  is  an  array  of  dimension  n  or  larger. 
When  SEIG  or  SEIGV1  is  called  the  eigenvalues  Ai,  . . . ,  An  and  corresponding  orthonormal 
eigenvectors  z1?  . ..,zn  are  computed.  The  eigenvalues  are  stored  in  W(  1),  ...,W(n)  and 
are  ordered  so  that  Ai  <  •  •  ■  <  A„. 

A  must  be  in  the  standard  format,  having  the  dimension  ka  x  n.  It  is  assumed  that 
ka  >  n.  However,  it  is  not  required  that  A(t, j)  be  defined  for  i  <  j.  Only  the  lower 
triangular  elements  of  A  are  used. 

Z  is  an  array  of  dimension  ka  x  n  or  larger.  For  j  =  1,  . . . ,  n  the  components  of  the 
eigenvector  zy  are  stored  in  the  jth  column  of  Z  (in  locations  Z(l,j),  . . .  ,Z(n,j)).  To 
conserve  memory  one  can  let  A  and  Z  denote  the  same  array. 

T  is  an  array  of  dimension  n  used  for  temporary  storage. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are 
found  then  IERR  is  set  to  0.  Otherwise,  if  more  than  30  iterations  of  the  QL  algorithm 
are  required  to  compute  the  jth  eigenvalue  Ay,  then  IERR  is  set  to  j.  In  this  case,  if  j  >  1 
then  the  eigenvalues  Ai,  .  ..,Ay_j  and  eigenvectors  z\,  .  ..,zy_i  will  have  been  computed 
and  stored  in  the  W  and  Z  arrays.  However,  the  eigenvalues  will  be  unordered. 

Note.  A  is  destroyed  during  computation. 

Programming.  SEIGV  and  SEIGVI  are  driver  routines  for  the  EISPACK  subroutines 
TRED2,  TQL2,  and  IMTQL2.  These  subroutines  were  developed  at  Argonne  National 
Laboratory.  The  function  SPMPAR  is  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  ah,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


311 


COMPUTATION  OF  EIGENVALUES  OF  COMPLEX  MATRICES 

The  subroutine  CEIG  is  available  for  computing  the  eigenvalues  of  complex  matrices. 
This  routine  frequently  yields  results  accurate  to  13-14  significant  digits.  However,  if  the 
eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly  clustered,  then  a  severe  drop 
in  accuracy  can  occur.  In  this  case  one  should  not  expect  more  than  7-8  digit  accuracy. 

CALL  CEIG(IBAL,AR,AI,  ka,  n,  WR,WI,IERR) 

AR  and  AI  are  real  matrices  of  order  n  >  1,  and  WR  and  WI  are  real  arrays  of 
dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  portions  of  the  complex  matrix 
whose  eigenvalues  are  to  be  computed.  When  CEIG  is  called  the  eigenvalues  A1(  . . . ,  A„ 
are  computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  . . .  ,WR(n)  and  the 
imaginary  parts  are  stored  in  WI(1),  . ..  ,WI(n).  The  eigenvalues  are  unordered. 

IBAL  and  ka  are  input  arguments.  It  is  assumed  that  ka  is  the  number  of  rows  in  the 
dimension  statements  for  AR  and  AI  in  the  calling  program.  IBAL  may  be  any  integer. 
If  IBAL  ■£  0  then  the  complex  matrix  (represented  by  AR  and  AI)  is  balanced  before  the 
eigenvalues  are  computed.  Otherwise,  if  IBAL  =  0  then  the  complex  matrix  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  IERR  is  set 
to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the  jth  eigenvalue  A j, 
then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then  the  eigenvalues 
Ay+1,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  in  a  slight  loss  of  accuracy.  On  the  other 
hand,  balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the 
accuracy  by  as  much  as  5-6  significant  digits.  Thus  it  is  recommended  that  balancing 
be  done. 

(2)  AR  and  AI  are  destroyed  during  computation.  CEIG  reduces  the  complex  matrix 
(represented  by  AR  and  AI)  to  upper  Hessenberg  form  with  unitary  similarity  trans¬ 
formations.  Then  the  QR  algorithm  is  used  to  obtain  the  eigenvalues. 

Usage.  If  one  has  a  complex  matrix  A,  then  AR  and  AI  can  be  obtained  using  the  matrix 
subroutines  CMREAL  and  CMIMAG. 

Programming.  CEIG  is  a  driver  routine  for  the  EISPACK  subroutines  CBAL,  CORTH, 
and  COMQR.  These  subroutines  were  developed  at  Argonne  National  Laboratory.  The 
functions  SPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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COMPUTATION  OF  EIGENVALUES  AND  EIGENVECTORS  OF 

COMPLEX  MATRICES 

The  subroutine  CEIGV  is  available  for  computing  the  eigenvalues  and  eigenvectors 
of  complex  matrices.  This  routine  frequently  yields  values  for  the  eigenvalues  that  are 
accurate  to  13-14  significant  digits.  However,  be  aware  that  errors  in  the  eigenvalues,  no 
matter  how  seemingly  insignificant,  can  be  considerably  magnified  in  the  computation  of 
the  eigenvectors.  It  is  not  at  all  unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the 
eigenvalue  is  correct  to  within  2-3  units  of  the  14th  significant  digit,  but  the  components  of 
the  corresponding  eigenvector  are  only  accurate  to  9-10  significant  digits.  If  the  eigenvalues 
of  a  matrix  are  not  distinct  or  if  they  are  exceedingly  tightly  clustered,  then  a  severe  drop 
in  accuracy  can  occur.  In  this  case  one  should  not  expect  the  eigenvalues  to  have  more  than 
7-8  digit  accuracy,  and  the  situation  regarding  the  eigenvectors  is  totally  unpredictable. 
The  components  of  such  an  eigenvector  may  be  correct  to  6-7  significant  digits,  or  the 
eigenvector  may  not  even  be  an  eigenvector!  In  this  case  the  results  should  be  checked. 

CALL  CEIGV(IBAL,AR,AI,  Jfca,n,  WR,WI,ZR,ZI,IERR,TEMP) 

AR  and  AI  are  real  matrices  of  order  n  >  1  and  WR  and  WI  are  real  arrays  of 
dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  portions  of  the  complex 
matrix  whose  eigenvalues  and  eigenvectors  are  to  be  computed.  When  CEIGV  is  called 
the  eigenvalues  Ai,  . . . , A„  and  corresponding  eigenvectors  z i,  ...  ,zn  are  computed.  The 
real  parts  of  the  eigenvalues  are  stored  in  WR(1),  ...,WR(n)  and  the  imaginary  parts  are 
stored  in  WI(1),  . . .  ,WI(n).  The  eigenvalues  are  unordered. 

It  is  assumed  that  the  input  argument  ka  is  the  number  of  rows  in  the  dimension 
statements  for  AR  and  AI  in  the  calling  program.  ZR  and  ZI  are  real  arrays  of  dimension 
ka  X  n.  For  j  =  1,  ...  ,n  the  real  parts  of  the  components  of  the  eigenvector  zy  are  stored 
in  the  jth  column  of  ZR  (in  locations  ZR(l,j),  ...  ,ZR(n,j))  and  the  imaginary  parts  are 
stored  in  the  jth  column  of  ZI.  The  eigenvectors  zx,  . . .  ,zn  are  not  normalized. 

IBAL  is  an  input  argument  that  can  be  assigned  any  integer  value.  If  IBAL  ^  0 
then  the  complex  matrix  (represented  by  AR  and  AI)  is  balanced  before  the  eigenvalues 
and  eigenvectors  are  computed.  Otherwise,  if  IBAL  =  0  then  the  complex  matrix  is  not 
balanced. 

TEMP  is  a  real  array  used  for  temporary  storage  by  the  routine.  If  no  balancing  is  to 
be  done  (i.e.,  if  IBAL  =  0)  then  TEMP  must  be  of  dimension  2n  or  larger.  Otherwise,  if 
balancing  is  to  be  performed  then  TEMP  must  be  of  dimension  3n  or  larger. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are  found 
then  IERR  is  set  to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the  jth 
eigenvalue  Ay,  then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then 
the  eigenvalues  Ay+i,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and 
WI  arrays.  However,  none  of  the  eigenvectors  will  have  been  computed.  The  eigenvectors 
are  computed  only  after  all  the  eigenvalues  have  been  obtained. 
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Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  in  a  slight  loss  of  accuracy.  On  the  other  hand, 
balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the  accuracy 
of  the  eigenvalues  by  as  much  as  5-6  significant  digits.  When  this  occurs  balancing 
will  normally  be  needed  to  obtain  the  eigenvectors.  In  general,  it  is  recommended  that 
balancing  be  done. 

(2)  AR  and  AI  are  destroyed  during  computation.  CEIGV  reduces  the  complex  matrix 
(represented  by  AR  and  AI)  to  upper  Hessenberg  form  with  unitary  similarity  trans¬ 
formations.  Then  the  QR  algorithm  is  employed  to  obtain  the  eigenvalues,  and  back- 
substitution  is  performed  to  generate  the  eigenvectors. 

Usage.  If  one  has  a  complex  matrix  A,  then  AR  and  AI  can  be  obtained  using  the  matrix 
subroutines  CMREAL  and  CMIMAG. 

Programming.  CEIGV  is  a  driver  routine  for  the  EISPACK  subroutines  CBAL,  CORTH, 
COMQR2,  and  CBABK2.  These  subroutines  were  developed  at  Argonne  National  Labora¬ 
tory.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  OF 

COMPLEX  MATRICES 

The  subroutine  DCEIG  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  of  complex  matrices.  This  routine  frequently  yields  results  accurate  to  26-28  signif¬ 
icant  digits.  However,  if  the  eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly 
clustered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one  should  not  expect 
more  than  13-14  digit  accuracy. 

CALL  DCEIG (IBAL, AR, AI,  fca,n,  WR,WI,IERR) 

AR  and  AI  are  double  precision  matrices  of  order  n  >  1,  and  WR  and  WI  are  double 
precision  arrays  of  dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  parts  of 
the  matrix  whose  eigenvalues  are  to  be  computed.  When  DCEIG  is  called  the  eigenvalues 
Ai,  . . . ,  An  are  computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(l),  . . .  ,WR(n) 
and  the  imaginary  parts  are  stored  in  WI(1),  ... ,  WI(n).  The  eigenvalues  are  unordered. 

IBAL  and  ka  are  input  arguments.  It  is  assumed  that  ka  is  the  number  of  rows  in  the 
dimension  statements  for  AR  and  AI  in  the  calling  program.  IBAL  may  be  any  integer. 
If  IBAL  ^  0  then  the  complex  matrix  (represented  by  AR  and  AI)  is  balanced  before  the 
eigenvalues  are  computed.  Otherwise,  if  IBAL  =  0  then  the  complex  matrix  is  not  balanced. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  IERR  is  set 
to  0.  Otherwise,  if  more  than  50  iterations  are  required  to  compute  the  jth  eigenvalue  Ay, 
then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then  the  eigenvalues 
Ay+ 1,  . . . ,  An  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  AR  and  AI  are  destroyed  during  computation. 

(2)  DCEIG  is  a  double  precision  version  of  the  eigenvalue  routine  CEIG. 

Programming.  DCEIG  is  a  driver  routine  for  the  subroutines  DCBAL,  DCORTH,  and 
DCOMQR.  These  subroutines  are  double  precision  versions  of  the  EISPACK  subroutines 
CBAL,  CORTH,  and  COMQR,  developed  at  Argonne  National  Laboratory.  The  double 
precision  versions  were  prepared  by  A.  H.  Morris.  The  functions  DCPABS,  DPMPAR, 
IPMPAR  and  subroutine  DCSQRT  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  AND 
EIGENVECTORS  OF  COMPLEX  MATRICES 

The  subroutine  DCEIGV  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  and  eigenvectors  of  complex  matrices.  The  routine  frequently  yields  values  for  the 
eigenvalues  that  are  accurate  to  26-28  significant  digits.  However,  be  aware  that  the  errors 
in  the  eigenvalues,  no  matter  how  seemingly  insignificant,  can  be  considerably  magnified 
in  the  computation  of  the  eigenvectors.  If  the  eigenvalues  are  not  distinct  or  if  they  are 
exceedingly  tightly  clustered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one 
should  not  expect  the  eigenvalues  to  have  more  than  13-14  digit  accuracy. 

CALL  DCEIGV(IBAL,AR,AI,  ka,  n,  WR,WI,ZR,ZI,IERR,TEMP) 

AR  and  AI  are  double  precision  matrices  of  order  n  >  1  and  WR  and  WI  are  double 
precision  arrays  of  dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  portions 
of  the  complex  matrix  whose  eigenvalues  and  eigenvectors  are  to  be  computed.  When 
DCEIGV  is  called  the  eigenvalues  Ai,  . . .  ,An  and  corresponding  eigenvectors  Z\,  ...  ,zn  are 
computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  ...,  WR(n)  and  the 
imaginary  parts  are  stored  in  WI(l),  . . .  ,WI(n).  The  eigenvalues  are  unordered. 

It  is  assumed  that  the  input  argument  ka  is  the  number  of  rows  in  the  dimension 
statements  for  AR  and  AI  in  the  calling  program.  ZR  and  ZI  are  double  precision  arrays  of 
dimension  ka  X  n.  For  j  =  1,'  . . . ,  n  the  real  parts  of  the  components  of  the  eigenvector  Zj 
are  stored  in  the  jth  column  of  ZR  (in  locations  ZR(l,j),  . . .  ,ZR (n, jr'))  and  the  imaginary 
parts  are  stored  in  the  jth  column  of  ZI.  The  eigenvectors  z\,  . . .  ,zn  are  not  normalized. 

IBAL  is  an  input  argument  that  can  be  assigned  any  integer  value.  If  IBAL  ^  0 
then  the  complex  matrix  (represented  by  AR  and  AI)  is  balanced  before  the  eigenvalues 
and  eigenvectors  are  computed.  Otherwise,  if  IBAL  =  0  then  the  complex  matrix  is  not 
balanced. 

TEMP  is  a  double  precision  array  used  for  temporary  storage  by  the  routine.  If  no 
balancing  is  to  be  done  (i.e,,  if  IBAL  =  0)  then  TEMP  must  be  of  dimension  2n  or  larger. 
Otherwise,  if  balancing  is  to  be  performed  then  TEMP  must  be  of  dimension  3n  or  larger. 

Error  Return.  IERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are  found 
then  IERR  is  set  to  0.  Otherwise,  if  more  than  50  iterations  are  required  to  compute  the  jth 
eigenvalue  A  y,  then  IERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then 
the  eigenvalues  Ay+i,  . . . ,  An  will  have  been  computed  and  the  results  stored  in  the  WR  and 
WI  arrays.  However,  none  of  the  eigenvectors  will  have  been  computed.  The  eigenvectors 
are  computed  only  after  all  the  eigenvalues  have  been  obtained. 

Remarks. 

(1)  AR  and  AI  cure  destroyed  during  computation. 

(2)  DCEIGV  is  a  double  precision  version  of  the  eigenvalue/eigenvector  routine  CEIGV. 
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Programming.  DCEIGV  is  a  driver  for  the  subroutines  DCBAL,  DCORTH,  DCMQR2, 
and  DCBABK.  These  subroutines  are  double  precision  versions  of  the  EISPACK  routines 
CBAL,  CORTH,  COMQR2,  and  CBABK2,  developed  at  Argonne  National  Laboratory. 
The  double  precision  versions  were  prepared  by  A.  H.  Morris.  The  functions  DCPABS, 
DPMPAR,  IPMPAR  and  subroutine  DCSQRT  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al.,  Matrix  Eigensystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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h  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS  WITH 
EQUALITY  AND  INEQUALITY  CONSTRAINTS 


Let  Abeafcxn  matrix,  C  an  £x  n  matrix,  and  E  an  mxn  matrix.  Also  let  b,  d,  and  /  be 

column  vectors  of  dimensions  k,  £,  and  m  respectively.  The  following  subroutine  is  available 

Jte 

for  obtaining  a  column  vector  x  of  dimension  n  which  minimizes  | \Ax  —  6||i  =  | A^z  —  |  v 

*=i 

subject  to  the  constraints 

Cx  =  d 
Ex  <  f. 


Here  Ai  denotes  the  tth  row  of  A,  and  Ex  <  f  means  that  every  component  of  Ex  is  less 
than  or  equal  to  the  corresponding  component  of  /. 

CALL  CLl(fc,  £,  m,  n,Q,kq,  KODE,TOL,ITER, X,  RES,RNORM,WK,IWK) 

It  is  assumed  that  k  >  1,  £  >  0,m  >  o,  and  n  >  1.  Q  is  a  2-dimensional  array  with 
kq  rows  and  at  least  n  +  2  columns  where  kq  >  k  +  £  +  m  +  2.  The  matrices  A,  C,  E  and 
vectors  b,  d,  f  are  stored  in  the  first  k  +  £  +  m  rows  and  n  +  1  columns  of  Q  as  follows: 


Q  is  modified  by  the  routine. 

KODE  is  a  variable  used  for  input/output  purposes,  X  an  array  of  dimension  n  +  2  or 
larger,  and  RES  an  array  of  dimension  k  +  £  +  m  or  larger.  On  input  KODE  is  normally 
set  by  the  user  to  0.  This  indicates  that  || Ax  —  6||i  is  to  be  minimized  subject  only  to  the 
constraints  Cx  =  d  and  Ex  <  f  .  However,  if  it  is  also  desired  that  one  or  more  variables 
x3-  satisfy  Xj  <  0  or  Xj  >  0,  or  that  one  or  more  residuals  bi  —  Ajx  satisfy  6,  —  A^x  <  0  or 
b{  —  AiX  >  0,  then  the  user  may  set  KODE  to  a  nonzero  value.  If  KODE  ^  0  on  input, 
then  the  user  must  also  set  X(j)  and  RES(i)  to  the  values 


m  = 


RES  (i)  = 


-1.0  x3-  <  0 
0.0  Xj  is  unrestricted 

1.0  Xj  >  0 

—  1.0  bi  —  AiX  <  0 

0.0  6,-  —  AiX  is  unrestricted 

1.0  6,-  —  AiX  >  0 


for  j  =  1,  .. .  ,n  and  t  =  1,  . .  .,k  to  indicate  the  additional  constraints  which  are  desired. 

RNORM  is  a  variable.  When  CL1  is  called,  if  a  vector  x  is  found  that  minimizes 
|| Ax  —  6 ||x  subject  to  the  desired  constraints,  then  KODE  =  0  on  output  and  the  solution  x 
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is  stored  in  X.  Also  RNORM  is  assigned  the  value  \\Ax  -b\\i,b  —  Ax  is  stored  in  the  first  k 
locations  of  RES,  d  —  Cx  is  stored  in  the  next  £  locations,  and  /  —  Ex  is  stored  in  the  last 
m  locations. 

When  CL1  is  called,  a  modified  form  of  the  simplex  algorithm  is  used  to  minimize 
|| Ax  —  &| | x ■  The  arguments  TOL  and  ITER  control  the  use  of  this  algorithm.  The  input 
argument  TOL  is  a  positive  tolerance.  CL1  will  not  pivot  on  any  quantity  whose  magnitude 
is  less  than  TOL.  Normally  the  setting  TOL  =  10-2"/3  suffices  where  u  is  the  number  of 
decimal  digits  of  accuracy  available. 

Frequently  the  routine  requires  less  than  5(fc+£+m)  iterations  of  the  simplex  alogrithm 
to  solve  the  problem.  ITER  is  a  variable  used  for  input/output  purposes.  On  input  the  user 
must  set  ITER  to  the  maximum  number  of  iterations  that  will  be  permitted.  When  the 
routine  terminates,  ITER  has  for  its  value  the  number  of  iterations  that  were  performed. 

On  output  KODE  reports  the  status  of  the  results.  The  routine  assigns  KODE  one  of 
the  following  values: 

KODE  =  0  The  problem  was  solved. 

KODE  =  1  The  problem  has  no  solution. 

KODE  =  2  Sufficient  accuracy  cannot  be  maintained  to  solve  the  problem 
using  the  current  value  of  TOL. 

KODE  =  3  The  maximum  number  of  iterations  were  performed.  More  itera¬ 
tions  are  needed. 

When  KODE  >  1  on  output,  X  contains  the  last  vector  x  which  was  obtained,  RNORM  = 
\\Ax  —  6||i,  and  RES  contains  the  vectors  b  —  Ax, d  —  Cx,  and  /  —  Ex. 

WK  is  an  array  of  dimension  2 (k  +  £  +  m  +  n)  or  larger,  and  IWK  is  an  array  of 
dimension  3(Jfc  +  £  +  m)  +  2 n  or  larger.  WK  and  IWK  are  work  spaces  for  the  routine. 

Programming.  CL1  calls  the  subroutine  KL1.  CL1  was  written  by  I.  Barrodale  and 
F.  D.  K.  Roberts  (University  of  Victoria,  British  Columbia,  Canada). 

References. 

(1)  Barrodale,  I.  and  Roberts,  F.  D.  K.,  “An  Improved  Algorithm  for  Discrete  t\  Linear 
Approximation,”  SIAM  J.  Numer.  Analysis  10  (1973),  pp.  839-848. 

(2)  _ ,  “An  Efficient  Algorithm  for  Discrete  t\  Linear  Approximation  with  Linear- 

Constraints,”  SIAM  J.  Numer.  Analysis  15  (1978),  pp.  603-611. 

(3)  _ ,  “Algorithm  552,  Solution  of  the  Constrained  L\  Linear  Approximation 

Problem,”  ACM  Trans.  Math  Software  6  (1980),  pp.  231-235. 
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LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 


Given  an  m  x  n  matrix  A  and  an  m  x  i  matrix  B.  The  column  vectors  blt  . . . ,  bi  of  B 
specify  l  distinct  linear  least  squares  problems 

Axj  =  bj  (i=l,. 

This  set  of  problems  can  be  written  in  the  form  AX  =  B  where  X  is  the  nxi  matrix  having 
the  column  vectors  x\,  ... ,  x/_.  There  always  exists  a  unique  minimum  length  least  squares 
solution  x j  for  each  Axj  =  bj.  The  subroutines  LLSQ,  HFTI,  and  HFTI2  are  available  for 
obtaining  the  minimum  length  solution  matrix  X.  HFTI  and  HFTI2  are  more  general  than 
LLSQ,  being  able  to  solve  arbitrary  systems  AX  =  B.  LLSQ  assumes  that  m  >  n  >  1  and 
that  the  rank  of  A  is  n.  The  routines  perform  Householder  triangular ization.  HFTI  and 
HFTI2  require  more  time  than  LLSQ,  but  may  be  more  accurate.  In  LLSQ  all  calculations 
are  performed  in  single  precision.  In  HFTI  and  HFTI2  most  inner  products  are  computed 
in  double  precision  and  the  results  stored  in  single  precision. 

CALL  LLSQ(m,  n,  A,  ka,  B,kb,  t,  WK,IWK,IERR) 

It  is  assumed  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  The  input  arguments  ka 
and  kb  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m  and  kb  >  m. 

IERR  is  an  integer  variable.  When  LLSQ  is  called,  if  no  input  errors  are  detected  then 
IERR  is  set  to  0  and  the  solution  matrix  X  stored  in  B.  Also,  if  m  ^  n  then  the  residual 
norm  || Axj  —  6y||  is  computed  and  stored  in  B(n  +  1  ,j)  for  j  =  1,  . . . ,  £.* 

WK  and  IWK  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routine. 

Error  Return.  IERR  7^  0  when  m  >  n  >  1  is  not  satisfied  (IERR  =  1)  or  the  rank  of  A  is 
less  than  n  (IERR  =  2). 

Note.  A  is  destroyed  during  computation. 

Programming.  LLSQ  is  a  driver  for  the  subroutines  ORTHO  and  ORSOL,  written  by  Nai- 
Kuan  Tsao  and  Paul  J.  Nikolai  (Aerospace  Research  Laboratories,  Wright-Patterson  Air 
Force  Base). 

Reference.  Tsao,  N.  K.  and  Nikolai,  P.  J.,  Procedures  using  Orthogonal  Transformations 
for  Linear  Least  Squares  Problems.  Report  ARL  TR  74-0124,  Aerospace  Research  Lab¬ 
oratories,  Wright-Patterson  Air  Force  Base,  1974. 

throughout  this  section  ||c||  =  for  any  vector  e=  (ci,  . ..,cm). 
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CALL  HFTI (A,  ka,  m,  n,  B,  kb,  t, r,  k,  RNORM,  H,G,  IP) 

CALL  HFTI2(A,  ka,  m,  n,  B,  kb,  l,  D,  t,  k,  RNORM,  H,  G,  IP,IERR) 

It  is  assumed  that  m,  n  >  1  and  that  the  input  arguments  ka  and  kb  have  the  following 
values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m.  Also,  if  t  >  1  then  kb  >  max{m,n}. 

If  l  >  1  then  RNORM  is  an  array  of  dimension  t  or  larger.  When  HFTI  or  HFTI2 
is  called,  the  minimum  length  solution  matrix  X  is  computed  and  stored  in  B.  Also  the 
residual  norm  || Axj  —  6y||  is  computed  and  stored  in  RNORM(y)  for  j  =  1,  . . .  ,£. 

H,  G,  and  IP  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routines. 

The  parameters  r,fc,  and  D. 

The  argument  r  is  a  tolerance  that  is  set  by  the  user,  k  a  variable,  and  D  an  array  of 
dimension  min{m,n}  or  larger.  It  is  assumed  that  r  >  0.  Normally  r  =  0  is  the  setting 
that  is  used.  D  and  k  are  set  by  the  routines. 

In  order  to  understand  the  use  of  r,  k,  and  D  one  must  be  briefly  acquainted  with  the 
processing  of  A.  The  routines  first  reduce  A  to  a  triangular  matrix  C  where  A  =  QCP. 
Q  is  an  orthogonal  matrix  and  P  a  permutation  matrix.  P  is  defined  so  that  the  diagonal 
elements  cu  of  C  satisfy  |c,»|  >  |c,+iii+1|  for  each  i.  The  variable  k  is  set  to  the  largest 
integer  such  that  |cfcjt|  >  r,  and  if  HFTI2  is  used  then  the  diagonal  elements  cu  are  stored 
in  D.  C  is  now  regarded  as  the  partitioned  matrix 


C  = 


(Cx  C2\ 

V  0  C3J 


where  Cx  is  a  k  x  k  matrix.  Minimum  length  least  squares  solutions  Xj  are  then  computed 
for  the  problems  Axj  =  bj  using  only  the  first  k  rows  of  C.  This  is  equivalent  to  replacing 
A  with 


A  =  Q 


and  solving  Axj  =  bj  for  j  =  1,  . . . ,  L 

Since  |cn|  >  >  |c*ij  >  r  clearly  k  is  the  rank  of  A.  It  is  also  true  that  the 

ratio  |cu|  /  |cjtfc[  is  a  lower  bound  on  the  condition  number  of  C\  (relative  to  the  spectral 
norm).  Thus,  if  the  ratio  is  extremely  large  (say  >  108)  then  a  severe  loss  of  accuracy 
can  be  expected.  A  large  ratio  may  be  due  all  or  in  part  to  rank  deficiency  (or  near  rank 
deficiency)  of  the  matrix  A.  Fortunately,  rank  deficiency  is  frequently  not  too  difficult  to 
detect  and  cure.  When  A  is  rank  deficient  then  machine  roundoff  may  assign  c^k  a  small 
value,  say  10~14,  when  it  should  be  0.  The  cure  is  to  examine  the  diagonal  elements  c,-,- 
which  are  stored  in  D,  to  reset  t  so  as  to  eliminate  the  unwanted  ca’s,  and  then  to  rerun 
the  problem.  This  will  reduce  the  order  of  Cx,  thereby  lowering  the  rank  of  the  replacement 
matrix  A.  Cx  will  now  be  better  conditioned,  but  the  value  of  the  residual  norms  J  Axj  —  bj  | 
may  be  larger.  If  the  norms  do  increase,  then  the  solution  obtained  will  be  satisfactory  only 
if  the  size  of  the  increased  norms  fall  within  acceptable  bounds. 
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Remarks. 

(1)  The  variable  k  is  set  to  0  if  all  |c^j  <  r.  If  k  =  0  then  the  zero  matrix  is  the  solution 
for  AX  —  B. 

(2)  If  £  <  0  then  the  decomposition  A  =  QCP  is  performed,  the  diagonal  elements  of  C 
are  stored  in  D,  and  k  is  computed.  B  and  RNORM  are  ignored. 

(3)  The  contents  of  A  are  destroyed  by  the  routines. 

(4)  HFTI  and  HFTI2  yield  the  same  results. 

Error  Return.  IERR  is  a  variable  that  is  set  by  the  routine.  If  no  input  errors  are  detected 
then  IERR  is  set  to  0.  Otherwise,  IERR  is  assigned  one  of  the  following  values: 

IERR  =1  if  m  >  ka 

IERR  =  2  if  £  >  I  and  kb  <  max  {m,  n} 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Programming.  HFTI  and  HFTI2  call  the  subroutine  H12.  These  routines  were  written  by 
Charles  L.  Lawson  and  Richard  J.  Hanson  (Jet  Propulsion  Laboratory),  and  modified  by 
A.  H.  Morris. 

Reference.  Lawson,  C.  L.,  and  Hanson,  R.  J.,  Solving  Least  Squares  Problems,  Prentice- 
Hall,  Inc.,  Englewood  Cliffs,  New  Jersey,  1974. 
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LEAST  SQUARES  SOLUTION  OF  OVERDETERMINED  SYSTEMS  OF 
LINEAR  EQUATIONS  WITH  ITERATIVE  IMPROVEMENT 

Given  an  m  x  n  matrix  A  and  an  m  x  £  matrix  B.  The  column  vectors  blt  . . . ,  bt  of  B 
specify  t  distinct  linear  least  squares  problems 

Axj  =  bj  {j  =  1, 

This  set  of  problems  can  be  written  in  the  form  AX  =  B  where  X  is  the  nxi  matrix  having 
the  column  vectors  Zj,  . . .  ,zt.  Assume  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  Then 
there  exists  a  unique  least  squares  solution  Xj  for  each  Axj  =  bj.  The  subroutine  LLSQMP 
is  available  for  obtaining  the  solution  matrix  X.  Iterative  improvement  is  performed  to 
compute  X  to  machine  accuracy. 

CALL  LLSQMP(m,  n,  A,  ka,  B,kb,  i,  WK,IWK,IERR) 

It  is  assumed  that  m  >  u  >  1  and  that  the  rank  of  A  is  n.  The  input  arguments  ka 
and  kb  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m  and  kb  >  m. 

When  LLSQMP  is  called,  the  solution  X  is  computed  and  stored  in  B.  Also,  if  m  ^  n 
then  the  residual  norm  || Aij  —  6y||  is  computed  and  stored  in  B{n  +  l,j)  for  j  =  1,  . . .  ,1* 
A  is  not  modified  by  the  routine. 

WK  is  an  array  of  dimension  mn  +  2m  +  n  or  larger,  and  IWK  an  array  of  dimension 
n  or  larger.  WK  and  IWK  are  work  spaces  for  the  routine. 

IERR  is  a  variable  that  is  set  by  the  routine.  When  LLSQMP  terminates,  IERR  has 
one  of  the  following  values: 

IERR  =  0  The  solution  X  was  computed  to  machine  accuracy. 

IERR  =  1  I  was  obtained,  but  not  to  machine  accuracy. 

IERR  =  2  The  restriction  m  >  n  >  1  is  not  satisfied. 

IERR  =  3  The  rank  of  A  is  less  than  n. 

Programming.  LLSQMP  is  a  driver  for  the  subroutines  ORTHO,  ORSOL,  and  ORIMP. 
These  subroutines  were  written  by  Nai-Kuan  Tsao  and  Paul  J.  Nikolai  (Aerospace  Research 
Laboratories,  Wright-Patterson  Air  Force  Base).  ORIMP  was  modified  by  A.  H.  Morris. 
The  function  SPMPAR  and  subroutine  MCOPY  are  also  used. 

Reference.  Tsao,  N.  K.  and  Nikolai,  P.  J.,  Procedures  using  Orthogonal  Transformations 
for  Linear  Least  Squares  Problems,  Report  ARL  TR  74-0124,  Aerospace  Research  Lab¬ 
oratories,  Wright-Patterson  Air  Force  Base,  1974. 


xHere  ||c||  =  ^/SjC?  for  any  vector  c  =  (cj,  ...,cm). 
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DOUBLE  PRECISION  LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF 

LINEAR  EQUATIONS 


Given  an  m  x  n  matrix  A  and  an  m  x  £  matrix  B.  The  column  vectors  &i,  . . . ,  bt  of  B 
specify  £  distinct  linear  least  squares  problems 

Axi  =  bi  {j  =  1, 

This  set  of  problems  can  be  written  in  the  form  AX  =  B  where  X  is  the  n  x  £  matrix 
having  the  column  vectors  xj.,  . . . ,  xt.  There  always  exists  a  unique  minimum  length  least 
squares  solution  x3  for  each  Ax3  =  b3.  The  subroutines  DLLSQ,  DHFTI,  and  DHFTI2 
are  available  for  obtaining  the  minimum  length  solution  matrix  X.  DHFTI  and  DHFTI2 
are  more  general  than  DLLSQ,  being  able  to  solve  arbitrary  systems  AX  =  B.  DLLSQ 
assumes  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  The  routines  perform  all  calculations 
in  double  precision. 

CALL  DLLSQ(m,  n,  A,  ka,  B,  kb,£,  WK,IWK,IERR) 

A  and  B  are  double  precision  arrays.  It  is  assumed  that  m  >  n  >  1  and  that  the  rank 
of  A  is  n.  The  input  arguments  ka  and  kb  have  the  following  values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m  and  kb  >  m. 

IERR  is  an  integer  variable.  When  DLLSQ  is  called,  if  no  input  errors  are  detected 
then  IERR  is  set  to  0  and  the  solution  matrix  X  stored  in  B.  Also,  if  m  ^  n  then  the 
residual  norm  || Ax3-  —  fey ||  is  computed  and  stored  in  B{n  +  1,  j)  for  j  =  1,  . . . ,  £} 

WK  and  IWK  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routine. 
WK  is  a  double  precision  array. 

Error  Return.  IERR  ^  0  when  m  >  n  >  1  is  not  satisfied  (IERR  =  1)  or  the  rank  of  A  is 
less  than  n  (IERR  =  2). 

Note.  A  is  destroyed  during  computation. 

Programming.  DLLSQ  calls  the  subroutines  DORTHO  and  DORSOL.  These  subroutines 
are  double  precision  versions  of  ORTHO  and  ORSOL,  written  by  Nai-Kuan  Tsao  and  Paul 
J.  Nikolai  (Aerospace  Research  Laboratories,  Wright-Patterson  Air  Force  Base). 

Reference.  Tsao,  N.  K.  and  Nikolai,  P.  J.,  Procedures  using  Orthogonal  Transformations 
for  Linear  Least  Squares  Problems.  Report  ARL  TR  74-0124,  Aerospace  Research  Lab¬ 
oratories,  Wright-Patterson  Air  Force  Base,  1974. 

throughout  this  section  ||c||  =  for  any  vector  c  =  (ci,  .. .  ,cm). 
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CALL  DHFTI (A,  ka,  m,  n,  B,  kb,  l,  t,  k,  RNORM,  H,  G,  IP) 

CALL  DHFTI2(A,  ka,  m,  n,  B,  kb,  t,  D,  r,  k,  RNORM,  if,G,IP,IERR) 

A  and  B  are  double  precision  arrays.  It  is  assumed  that  m,n  >  1  and  that  the  input 
arguments  ka  and  kb  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m,  Also,  if  £  >  1  then  kb  >  max{m,n}. 

If  l  >  1  then  RNORM  is  a  double  precision  array  of  dimension  £  or  larger.  When 
DHFTI  or  DHFTI2  is  called,  the  minimum  length  solution  matrix  X  is  computed  and 
stored  in  B.  Also  the  residual  norm  \\Axj  —  6y||  is  computed  and  stored  in  RNORM(j)  for 
j=l,...,L 

H,G,  and  IP  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routines. 
H  and  G  are  double  precision  arrays. 

The  parameters  r,k,  and  D. 

t  is  a  double  precision  tolerance  that  is  set  by  the  user,  k  an  integer  variable,  and 
D  a  double  precision  array  of  dimension  min{m,  n}  or  larger.  It  is  assumed  that  r  >  0. 
Normally  r  =  0  is  the  setting  that  is  used.  D  and  k  are  set  by  the  routines. 

In  order  to  understand  the  use  of  t,  k,  and  D  one  must  be  briefly  acquainted  with  the 
processing  of  A.  The  routines  first  reduce  A  to  a  triangular  matrix  C  where  A  =  QCP. 
Q  is  an  orthogonal  matrix  and  P  a  permutation  matrix.  P  is  defined  so  that  the  diagonal 
elements  c„  of  C  satisfy  |c,t|  >  |  for  each  i.  The  variable  k  is  set  to  the  largest 

integer  such  that  |cfc*|  >  r,  and  if  DHFTI2  is  used  then  the  diagonal  elements  are  stored 
in  D.  C  is  now  regarded  as  the  partitioned  matrix 

«-(?  a) 


where  C\  is  a  k  x  k  matrix.  Minimum  length  least  squares  solutions  xy  are  then  computed 
for  the  problems  Axy  ==  bj  using  only  the  first  k  rows  of  C.  This  is  equivalent  to  replacing 
A  with 


A-Q 


Ci  C2 
0  0 


p 


and  solving  Axy  =  bj  for  j  =  1,  ...,£. 

Since  |cn  !>•■•>  kfcfcl  >  r  clearly  k  is  the  rank  of  A.  It  is  also  true  that  the 
ratio  |cji|  /  is  a  lower  bound  on  the  condition  number  of  C\  (relative  to  the  spectral 
norm).  Thus,  if  the  ratio  is  extremely  large  (say  >  108)  then  a  severe  loss  of  accuracy 
can  be  expected.  A  large  ratio  may  be  due  all  or  in  part  to  rank  deficiency  (or  near  rank 
deficiency)  of  the  matrix  A.  Fortunately,  rank  deficiency  is  frequently  not  too  difficult  to 
detect  and  cure.  When  A  is  rank  deficient  then  machine  roundoff  may  assign  Ckk  a  small 
value,  say  10~28,  when  it  should  be  0.  The  cure  is  to  examine  the  diagonal  elements  ca 
which  are  stored  in  D,  to  reset  r  so  as  to  eliminate  the  unwanted  c^’s,  and  then  to  rerun 
the  problem.  This  will  reduce  the  order  of  C\,  thereby  lowering  the  rank  of  the  replacement 
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matrix  A.  C i  will  now  be  better  conditioned,  but  the  value  of  the  residual  norms  ||Asy  —  6y|| 
may  be  larger.  If  the  norms  do  increase,  then  the  solution  obtained  will  be  satisfactory  only 
if  the  size  of  the  increased  norms  fall  within  acceptable  bounds. 

Remarks. 

(1)  The  variable  k  is  set  to  0  if  all  |c„-|  <  r.  If  k  =  0  then  the  zero  matrix  is  the  solution 
for  AX  =  B. 

(2)  It  l  <  0  then  the  decomposition  A  —  QCP  is  performed,  the  diagonal  elements  of  C 
are  stored  in  D,  and  k  is  computed.  B  and  RNORM  are  ignored. 

(3)  The  contents  of  A  are  destroyed  by  the  routines. 

(4)  DHFTI  and  DHFTI2  yield  the  same  results.  These  routines  are  double  precision  ver¬ 
sions  of  the  subroutines  HFTI  and  HFTI2. 

Error  Return.  IERR  is  a  variable  that  is  set  by  the  routine.  If  no  input  errors  are  detected 
then  IERR  is  set  to  0.  Otherwise,  IERR  is  assigned  one  of  the  following  values: 

IERR  =1  if  m  >  ka 

IERR  =  2  if  £  >  1  and  kb  <  max  {m,  n} 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Programming.  DHFTI  and  DHFTI2  call  the  subroutine  DH12.  These  routines  are  modi¬ 
fications  by  A.  H.  Morris  of  the  subroutines  HFTI  and  H12,  written  by  Charles  L.  Lawson 
and  Richard  J.  Hanson  (Jet  Propulsion  Laboratory). 

Reference.  Lawson,  C.  L.,  and  Hanson,  R.  J.,  Solving  Least  Squares  Problems,  Prentice- 
Hall,  Inc.,  Englewood  Cliffs,  New  Jersey,  1974. 
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LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 
WITH  EQUALITY  AND  INEQUALITY  CONSTRAINTS 


Let  A  be  an  ma  x  n  matrix,  £aimexn  matrix,  G  an  mg  x  n  matrix,  b  a  column  vector 
of  dimension  ma,  f  a  column  vector  of  dimension  me,  and  h  a  column  vector  of  dimension 
mg.  The  subroutine  LSEI  is  available  for  finding  a  column  vector  x  of  dimension  n  that 
minimizes  ||Aa:  —  6|[  subject  to  the  constraints1 

Ex  ~  / 

Gx  >  h. 

Ex  ~  /  states  that  x  is  a  least  squares  solution  of  the  equation  Ex  =  /,  and  Gx  >  h  means 
that  every  component  of  the  vector  Gx  must  be  equal  to  or  greater  than  the  corresponding 
component  of  h.  It  is  assumed  that  ma  >  0,  me  >  0,  and  mg  >  0.  If  ma  =  0  then  LSEI 
solves  Ex  ~  /  subject  to  the  constraints  Gx  >  h. 

CALL  LSEI(W,fcu/,me,  ma,mg,  n,  OPT,  x,  RNORME, RNORMA, 
IERR,WK,IWK) 

If  m  =  me  +  m„  +  mg  then  W  is  the  m  X  (n  +  1)  matrix: 

(E  /\ 

W  =  A  6 
\G  h } 

The  input  argument  kw  is  assumed  to  have  the  value: 

kw  =  the  number  of  rows  in  the  dimension  statement  for  W  in  the  calling  program 
Thus  it  is  required  that  kw  >  m. 

RNORME  and  RNORMA  are  real  variables.  When  LSEI  is  called,  if  the  constraints 
Ex  ~  f  and  Gx  >  h  are  consistent  then  x  is  computed,  RNORME  is  assigned  the  value 
|| Ex  -  /||,  and  RNORMA  is  assigned  the  value  ||As  -  6||.2 

OPT  is  an  array,  called  the  option  vector,  which  permits  the  user  to  take  advantage  of 
certain  options  that  are  supplied  by  the  routine.  If  no  options  are  desired  then  OPT  may 
be  declared  to  have  dimension  1  and  OPT(l)  must  be  assigned  the  value  1.  The  details 
concerning  the  available  options  and  how  to  specify  them  in  OPT  are  given  below. 

IWK  is  an  array  of  dimension  mg  +  2n  +  2  or  larger,  and  WK  is  an  array  of  dimension 
2 (me  +  n)  +  max  {mtt  +  ms,n}  +  (ma  +  2)(n  +  7)  or  larger.  IWK  and  WK  are  work 
spaces.  When  LSEI  is  called,  using  a  solution  for  Ex  ~  /,  a  reduced  least  squares  problem 
with  inequality  constraints  is  obtained  and  solved.  When  the  routine  terminates  IWK(l), 
IWK(2),  IWK(3)  contain  the  following  information: 

throughout  this  section  ||c||  denotes  the  norm  -y/SjC?  for  any  vector  c  —  (ci,ca,  ...). 

2If  m«  -  0  then  RNORME  —  0,  and  if  m/  —  0  then  RNORMA  =  0. 
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the  estimated  rank  of  the  matrix  E 
the  estimated  rank  of  the  reduced  problem 

the  amount  of  storage  in  the  array  WK  that  was  actually  needed 

IERR  is  a  variable  that  is  set  by  the  routine.  When  LSEI  terminates,  IERR  has  one 
of  the  following  values: 

IERR  =  0  The  solution  x  was  obtained.  The  equality  Ex  —  f  is  satisfied 
when  me  0. 

IERR  =  1  The  solution  x  was  obtained.  In  this  case  || Ex  —  f  \\  >  0. 

IERR  =  2  The  problem  cannot  be  solved.  The  constraints  are  inconsistent. 

IERR  =  4  (Input  error)  Either  kw  <  m,  the  covariance  matrix  is  requested 
and  kw  <  n,  or  the  option  vector  OPT  is  not  defined  properly. 

If  IERR  >  2  then  x,  RNORME,  and  RNORMA  are  not  defined. 

Remarks. 

(1)  W  is  modified  by  the  routine. 

(2)  If  me  +  ma  <  0  or  n  <  0  then  IERR  is  set  to  0  and  the  routine  terminates. 

The  option  vector  OPT.  If  no  options  are  desired  then  OPT  may  be  declared  to  be  of 
dimension  1  and  OPT(l)  must  have  the  value  1.  Otherwise,  OPT  is  a  linked  list  consisting 
of  groups  of  data  link;,  key,-,  data,-  (»'  =  1,  . . .  ,s).  Each  link,-  and  key;  is  an  integer.  The 
amount  of  storage  required  by  data;  depends  on  the  value  of  key;.  The  general  layout  of 
OPT  is  as  follows: 

OPT(l)  =  linki  (index  of  the  first  entry  of  the  next  group) 

OPT(2)  =  key!  (key  to  the  option) 

OPT(3)  =  the  first  word  of  the  data  (datai)  for  this  option 


OPT(linki)  =  link2  (index  of  the  first  entry  of  the  next  group) 
OPT(linki  +  1)  =  key2  (key  to  the  option) 

OPT(linki  +  2)  =  the  first  word  of  the  data  (data2)  for  this  option 


IWK(l)  = 
IWK(2)  = 
IWK(3)  = 


OPT(links)  =  1.0  (There  are  no  more  options  to  be  considered.) 


The  following  options  are  available: 


key  = 


1  It  is  assumed  that  kw  >  n.  Compute  the  n  X  n  covariance  matrix 
and  store  it  in  the  first  n  rows  and  columns  of  W.  The  data  for 
this  option  is  a  single  value.  It  must  be  nonzero  for  the  covariance 
matrix  to  be  computed. 


2  Scale  the  nonzero  columns  of  the  matrix 


E\ 

A  so  that  they  have 

gJ 
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length  1.  The  data  for  this  option  is  a  single  value.  It  must  be 
nonzero  for  the  scaling  to  be  performed. 

key  =  3  Scale  the  columns  of  the  matrix  ^  a  ^ .  The  data  for  this  option 

consists  of  n  scaling  factors,  one  for  each  matrix  column. 

key  =  4  Change  the  internal  tolerance  r  which  is  used  for  determining  the 
rank  of  E.  The  data  for  this  option  is  the  new  tolerance,  r  may  be 
set  to  any  value  >  e  where  e  is  the  smallest  floating  point  number 
for  which  1  +  e  >  I(e  =  2~47  for  the  CDC  6700).  If  the  new  value 
is  less  than  e  then  it  is  ignored  and  r  is  set  to  e.  The  default  value 
employed  for  r  is  y/e. 

key  =  5  Change  the  internal  tolerance  r  which  is  used  for  rank  determi¬ 
nation  in  the  reduced  least  squares  problem.  The  data  for  this 
option  is  the  new  tolerance,  r  may  be  set  to  any  value  >  e  where 
e  is  the  smallest  floating  point  number  for  which  1  +  e  >  1.  If  the 
new  value  is  less  than  e  then  it  is  ignored  and  r  is  set  to  e.  The 
default  value  employed  for  r  is  y/e. 

Also  the  key  8  and  9  options  for  tbe  least  squares  subroutine  WNNLS  are  permitted. 
(WNNLS  is  employed  by  LSEI.)  The  order  of  the  options  in  the  array  OPT  is  arbitrary. 
If  an  option  has  an  unrecognized  key  then  the  option  is  ignored.  It  is  assumed  that  the 
dimension  of  OPT  is  no  greater  than  100000  and  that  the  number  of  options  is  <  1000.  If 
either  of  these  assumptions  is  violated  then  IERR  is  set  to  4  and  the  routine  terminates 
It  is  also  required  that  link,-  /  linky  for  i  /  j.  If  this  restriction  is  not  satisfied  then  the 
linked  list  OPT  is  circular  and  we  again  have  an  IERR  =  4  error.. 


Example.  Assume  that  we  have  an  array  D  containing  n  scaling  factors  for  the  columns  of 
the  matrix  ^  ,  and  that  the  tolerance  TOL  is  always  to  be  used  for  rank  determination. 

Then  OPT  will  have  to  be  of  dimension  >  n  +  9  and  OPT  can  be  defined  as  follows: 


OPT(l)  =  N  +  3 
OPT(2)  =  3.0 
DO  10  I  =  1,  IV 
10  OPT  (/  +  2)  =  D(I) 

OPT(l\T  +  3)  =  N  +  6 
OPT  {N  +  4)  =  4.0 
OPT(N  +  5)  =  TOL 
OPT(JV  +  6)  =  iV  +  9 
OPT(V  +  7)  =  5.0 
OPT(IV  +  8)  =  TOL 
OPT(IV  +  9)  =  1.0 


(Scaling  option) 


(Matrix  E  tolerance  option) 


(Reduced  problem  tolerance  option) 


(There  are  no  more  options.) 


Remarks. 

(1)  LSEI  may  perform  poorly  if  the  norms  of  the  rows  of  A  and  E  differ  by  many  orders 
of  magnitude,  or  if  the  norms  of  the  rows  of  E  axe  exceedingly  small. 

(2)  The  covariance  matrix  obtained  by  the  key  =  1  option  may  not  be  meaningful  when 
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there  are  inequality  constraints  Gx  >  h.  This  matrix  assumes  that  any  inequalities 
which  are  selected  by  the  algorithm  to  be  equalities  remain  equalities  when  the  solution 
is  perturbed.  This,  of  course,  may  not  be  the  case. 

Programming.  LSEI  employs  the  subroutine  LSI,  LPDP,  WNNLS,  WNLSM,  and  WNLIT. 

These  routines  were  written  by  Karen  H.  Haskell  and  Richard  J.  Hanson  (Sandia  Labora¬ 
tories)  and  modified  by  A.  H.  Morris.  The  subroutines  HFTI,  H12,  SROTM,  SROTMG, 

SCOPY,  SSWAP,  SSCAL,  SAXPY  and  functions  SPMPAR,  SDOT,  SASUM,  SNRM2, 

ISAMAX  are  also  used. 

References. 

(1)  Hanson,  R.  J.  and  Haskell,  K.  H.,  “Algorithm  587:  Two  Algorithms  for  the  Linearly 
Constrained  Least  Squares  Problem,”  ACM  Trans.  Math  Software  8  (1982),  pp. 
323-333. 

(2)  Haskell,  K.  H.  and  Hanson,  R.  J.,  “An  Algorithm  for  Linear  Least  Squares  Prob¬ 
lems  with  Equality  and  Nonnegativity  Constraints,”  Math.  Programming  21  (1981), 
pp.  98-118. 


336 


LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 
WITH  EQUALITY  AND  NONNEGATIVITY  CONSTRAINTS 


Let  A  be  an  mtt  X  n  matrix,  E  an  me  x  n  matrix,  b  a  column  vector  of  dimension  ma, 
and  /  a  column  vector  of  dimension  me  The  subroutine  WNNLS  is  available  for  finding  a 
column  vector  x  =  (zj,  . . . ,  in)‘  that  minimizes  \\Ax  —  6|[  subject  to  the  constraints1 

Ex  ~  / 

x  i  >  0  for  *  >  L 

Ex  ~  /  states  that  x  is  a  least  squares  solution  of  the  equation  Ex  =  /.  It  is  assumed  that 
ma  >  0 ,mt  >  0,  and  0  <  t  <  n.  If  ma  =  0  then  WNNLS  solves  Ex  ~  /  subject  to  the 
constraints  z,-  >  0  (t  >  £). 

CALL  WNNLS(W,  kw,  me,ma,  n,  £,  OPT,  z,  RNORM,MODE,IWK,WK) 

If  m  —  me  +  ma  then  W  is  the  m  X  (n  +  1)  matrix: 


The  input  argument  kw  is  assumed  to  have  the  value: 

kw  =  the  number  of  rows  in  the  dimension  statement  for  W  in  the  calling  progam 
Thus  it  is  required  that  kw  >  m. 

RNORM  is  a  variable.  When  WNNLS  is  called,  z  is  computed  and  RNORM  is  assigned 
the  value  \/|jAz  —  6||2  +  || Ex  —  f  ||2,2 

OPT  is  an  array,  called  the  option  vector,  which  permits  the  user  to  take  advantage  of 
certain  options  that  are  supplied  by  the  routine.  If  no  options  are  desired  then  OPT  may 
be  declared  to  have  dimension  1  and  OPT(l)  must  be  assigned  the  value  1.  The  details 
concerning  the  available  options  and  how  to  specify  them  in  OPT  are  given  below. 

IWK  is  an  array  of  dimension  m  +  n  or  larger,  and  WK  is  an  array  of  dimension  m  +  5n 
or  larger.  IWK  and  WK  are  work  spaces  for  the  routine. 

Error  Return.  MODE  is  an  integer  variable  that  is  set  by  the  routine.  If  the  problem 
is  solved  then  MODE  is  assigned  the  value  0.  Otherwise,  MODE  is  assigned  one  of  the 
following  values: 

MODE  =  1  The  maximum  number  of  iterations  (3(n  -  i)  iterations)  was  ex¬ 
ceeded.  An  approximate  solution  and  its  residual  norm  are  stored 
in  z  and  RNORM. 

MODE  =  2  (Input  error)  Either  kw  >  m  or  0<£<nis  violated,  or  the 
option  vector  OPT  is  not  properly  defined. 

throughout  this  section  ||c|[  denotes  the  norm  yj Sc?  for  any  vector  c  =  (ci,  ci ,  . . .). 

3If  ma  —  0  then  RNORM  =  || Ex  —  /||,  and  if  me  =  0  then  RNORM  =  \\Ax  —  6||. 
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When  an  input  error  is  detected,  the  routine  immediately  terminates.  In  this  case  x  and 
RNORM  are  not  defined. 

Remarks. 

(1)  W  is  modified  by  the  routine. 

(2)  If  m  <  0  or  n  <  0  then  MODE  is  set  to  0  and  the  routine  terminates. 

The  option  vector  OPT.  If  no  options  are  desired  then  OPT  may  be  declared  to  be  of 
dimension  1  and  OPT(l)  must  have  the  value  1.  Otherwise,  OPT  is  a  linked  list  consisting 
of  groups  of  data  link,,  key;,  data;  (t  =  1,  . . .  ,s).  Each  link,-  and  key,-  is  an  integer.  The 
amount  of  storage  required  by  data,-  depends  on  the  value  of  key,-.  The  general  layout  of 
OPT  is  as  follows: 

OPT(l)  =  link-i  (index  of  the  first  entry  of  the  next  group) 

OPT(2)  =  keyi  (key  to  the  option) 

OPT(3)  =  the  first  word  of  the  data  (datai)  for  this  option 


OPT(linki)  =  link2  (index  of  the  first  entry  of  the  next  group 

OPT(linki  +  1)  =  key2  (key  to  the  option) 

OPT(linki  +  2)  =  the  first  word  of  the  data  (data2)  for  this  option 


OPT(linka)  =  1.0  (There  are- no  more  options  to  be  considered.) 

The  following  options  are  permitted: 

key  =  6  Scale  the  nonzero  columns  of  the  matrix  ( ^ )  so  that  they  have 
length  1.  The  data  for  this  option  is  a  single  value.  It  must  be 
nonzero  for  the  scaling  to  be  performed, 
key  =  7  Scale  the  columns  of  the  matrix  ( ^ ).  The  data  for  this  option 
consists  of  n  scaling  factors,  one  for  each  matrix  column, 
key  =  8  Change  the  internal  tolerance  r  which  is  used  for  rank  determina¬ 
tion.  The  data  for  this  option  is  the  new  tolerance,  r  may  be  set 
to  any  value  >  e  where  e  is  the  smallest  floating  point  number  for 

which  1  +  €  >  1.  (c.=  2-47  for  the  CDC  6700.)  If  the  new  value  is 

less  than  e  then  it  is  ignored  and  r  is  set  to  e.  The  default  value 
employed  for  r  is  y/i. 

key  =  9  Change  the  parameter  BLOWUP.  The  reciprocal  of  this  parameter 
is  used  in  determining  when  solution  components  are  too  large. 
The  data  for  this  option  is  the  new  value  for  BLOWUP.  It  is 
assumed  that  BLOWUP  <  1.  BLOWUP  may  be  set  to  any  value 
>  e  where  e  is  the  smallest  number  for  which  1  +  e  >  1.  If  the  new 
value  is  less  than  e  then  it  is  ignored  and  BLOWUP  is  set  to  e. 
The  default  value  used  for  BLOWUP  is  \fk. 
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The  order  of  the  options  in  the  array  OPT  is  arbitrary.  If  an  option  has  an  unrecognized 
key  then  the  option  is  ignored.  It  is  assumed  that  the  dimension  of  OPT  is  no  greater  than 
100000  and  that  the  number  of  options  <  1000.  If  either  of  these  assumptions  is  violated 
then  MODE  is  set  to  2  and  the  routine  terminates.  It  is  also  required  that  link*  ^  linky  for 
*  ^  j.  If  this  restriction  is  not  satisfied  then  the  linked  list  OPT  is  circular  and  we  again 
have  a  MODE  =  2  error. 

Example.  Assume  that  we  have  an  array  D  containing  n  scaling  factors  for  the  columns  of 
the  matrix  (^),  and  that  TOL  is  the  tolerance  to  be  used  for  rank  determination.  Then 
OPT  will  have  to  be  of  dimension  >  n  +  6  and  OPT  can  be  defined  as  follows: 

OPT(l)  =  N  +  3  (Scaling  option) 

OPT(2)  =  7.0 
DO  10  1  =  1,N 
10  OPT(/+2)  =  D{I) 

OPT(iV  +  3)  =  N  +  6  (Tolerance  option) 

OPT(lV  +  4)  =  8.0 
OPT(lV  +  5)  =  TOL 

OPT(lV  +  6)  =  1.0  (There  are  no  more  options.) 

Remark.  WNNLS  may  perform  poorly  if  the  norms  of  the  rows  of  A  and  E  differ  by  many 
orders  of  magnitude,  or  if  the  norms  of  the  rows  of  E  are  exceedingly  small. 

Programming.  WNNLS  employs  the  subroutines  WNLSM  and  WNLIT.  These  routines 
were  written  by  Karen  H.  Haskell  and  Richard  J.  Hanson  (Sandia  Laboratories),  and  mod¬ 
ified  by  A.  H.  Morris  and  Virgis  Dadurkevicius  (Astronomical  Observatory,  Vilnius  Uni¬ 
versity,  Lithuania).  The  subroutines  H12,  SROTM,  SROTMG,  SCOPY,  SSWAP,  SSCAL, 
SAXPY  and  functions  SPMPAR,  SASUM,  SNRM2,  ISAMAX  are  also  used. 

References. 

(1)  Dadurkevicius, V., “Remark  on  Algorithm  587  ”ACM Trans.  Math  Software  15  (1989), 
pp.  257-261. 

(2)  Hanson,  R.  J.  and  Haskell,  K.  H.,  “Algorithm  587:  Two  Algorithms  for  the  Linearly 
Constrained  Least  Squares  Problem,”  ACM  Trans.  Math  Software  8  (1982),  pp.  323- 
333. 

(3)  Haskell,  K.  H.  and  Hanson,  R.  J.,  “An  Algorithm  for  Linear  Least  Squares  Problems 
with  Equality  and  Nonnegativity  Constraints,”  Math.  Programming  21  (1981),  pp. 
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LEAST  SQUARES  ITERATIVE  IMPROVEMENT  SOLUTION  OF  SYSTEMS 
OF  LINEAR  EQUATIONS  WITH  EQUALITY  CONSTRAINTS 


Let  A  be  an  ma  x  n  matrix,  E  an  me  x  n  matrix,  B  an  ma  x  £  matrix,  and  F  an 
me  x  £  matrix.  It  is  assumed  that  0  <  me  <  n  and  that  the  rank  of  E  is  m„.  Let  b1} 
denote  the  column  vectors  of  B  and  f\ ,  .  ■  ■  ,fi  the  column  vectors  of  F.  The  subroutine 
L2SLV  is  available  for  finding  the  unique  minimum  length  column  vector  xy  of  dimension 
n  that  minimizes  ||Axy  ~bj |]  subject  to  the  equality  constraints  Eij  =  /y  (if  there  are  any) 
for  j  =  1,  . . . , £.1  Iterative  improvement  is  performed  to  compute  the  vectors  xj,  ...  ,xi 
to  machine  accuracy.  It  is  assumed  that  ma  >  0.  If  ma  =  0  then  L2SLV  finds  the  unique 
minimum  length  solution  xy  to  Eij  =  fj  for  j  =  1,  . . .  ,£. 

CALL  L2SLV(m,  n,  me,  £,  A,  ka,  B,  kb,  WGTS>TOL,Nl,IPIVOT, 

X,  kx,  R,  kr,  T,  kt,  WK,IERR) 

If  m  =  me  +  m0  then  A  is  the  m  X  n  matrix  ( ^  )  and  B  is  the  m  X  £  matrix  ( ^ )  ■  The 
input  arguments  ka  and  kb  have  the  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  m  >  1,  n  >  1,£  >  1,  ka  >  m,  and  kb  >  m.  A  and  B  are  not  modified  by 
the  routine. 


WGTS  is  an  array  containing  m  nonnegative  weights.  The  first  me  weights  are  set  to  1.0 
by  the  routine.  Let  wi,  ..  .  ,u/mo  denote  the  remaining  weights  (i.e.,  let  tn*  =  WGTS(me+t) 
for  t  =  1,  . ..,m0).  The  remaining  weights  are  supplied  by  the  user.  In  effect,  is  the 
weighting  that  is  given  to  the  ith  equation  in  the  least  squares  problem  Axy  =  6y.  If 
W  denotes  the  ma  x  ma  diagonal  matrix  diag(ti>i,  .. . ,  wma)  then  L2SLV  finds  the  unique 
minimum  length  vector  that  minimizes  ||V7Axy  —  Wbj\\  subject  to  Eij  =  fj  for  j  =  1  ,...,£. 
For  convenience,  W  will  denote  the  m  x  m  diagonal  matrix  diag  (1,  . . . ,  1,  tuj,  . . . , 

X  is  an  n  x  £  matrix  that  contains  the  solution  vectors  Xi,  ...,Xt  when  the  routine 
terminates.  The  input  argument  kx  is  the  number  of  rows  in  the  dimension  statement  for 
X  in  the  calling  program.  It  is  assumed  that  kx  >  n. 

12  is  an  m  x  £  matrix.  Let  6y  denote  the  jth  column  vector  (  ^ )  of  B  for  j  =  1,  ...,£. 

Then  L2SLV  stores  the  residual  vector  ry  =  Wbj  —  WAxj  in  the  jth  column  of  i2.  The  input 
argument  kr  is  the  number  of  rows  in  the  dimension  statement  for  R  in  the  callifig  progam. 
It  is  assumed  that  kr  >  m. 


WK  is  an  array  of  dimension  6(m  +  n)  +  2£  or  larger  that  is  used  for  a  work  space. 
When  L2SLV  terminates,  for  j  =  1,  . . . ,  £ 


if  iterative  improvement  of  the  solution  xy  converged 
if  iterative  improvement  of  xy  failed  to  converge 


throughout  this  section  ||c||  denotes  the  norm  for  any  vector  c  =  (ci . 
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where  ny  is  the  number  of  iterations  in  the  iterative  improvement  process  that  were  per¬ 
formed  in  computing  Xj.  Also 

WK(£+j)  =  the  estimated  number  of  correct  digits  in  Xj  before  iterative  improvement 
was  performed 

for  j  =  1,  ...  ,1. 

TOL  and  N1  correspond  to  the  parameters  r  and  k  in  the  least  squares  subroutines 
HFTI  and  HFTI2.  TOL  is  a  nonnegative  number  that  is  specified  by  the  user,  and  N1 
is  a  variable  that  is  set  by  the  routine.  When  L2SLV  is  called,  modified  Gram-Schmidt 
orthogonalization  with  column  pivoting  is  used  to  reduce  WA  to  the  form  (Ai  A2)  where  A\ 
is  an  m  x  N\  matrix  having  rank  iVy.  Ai  is  of  the  form  Q U  where  Q*Q  =  diag(di,  . . . ,  d jyy ) 
and  U  is  an  upper  unit  triangular  matrix.  The  values  di,  d2 ,  . . .  correspond  to  the  diagonal 
elements  cn,c22,  . . .  generated  by  HFTI  and  HFTI2  (d,  =  for  t  =  1,2,  . . .  ).  The  values 

are  ordered  so  that  dt-  >  dt+i,  and  di,  d2,  . . .  are  stored  in  WK(2£  +  1),  WK(2£+  2), _ 

If  m  =  me  then  iVl  is  assigned  the  value  me.  Otherwise,  if  m  >  me  then  N 1  is  the  largest 
integer  k  for  which  dk  >  t.  Here  r  =  TOL  if  TOL  >  0,  and  t  =  (ne)2dme+i  where  e  is  the 
smallest  value  for  which  1  +  e  >  1  (e  =  2-47  on  the  CDC  6700)  if  TOL  =  0.  Thus,  if  TOL 
=  0  then  a  tolerance  based  on  the  computer  precision  is  used  to  determine  the  rank  of  N\ 
of  WA.  Otherwise,  if  TOL  >  0  then  TOL  is  the  tolerance  that  is  used  to  specify  the  rank 
of  the  problem  to  be  solved.  If  the  user  inadvertently  sets  TOL  to  be  negative  then  L2SLV 
resets  TOL  to  be  0. 

IPIVOT  is  an  array  of  dimension  n  or  larger  that  is  used  by  L2SLV  to  record  the  order 
in  which  the  columns  of  WA  are  selected  by  the  pivoting  procedure  when  WA  is  reduced  to 
(Ai A3).  If  N 1  <  n  then  the  first  N 1  elements  of  IPIVOT  are  the  indices  of  the  columns  of 
WA  from  which  the  matrix  Ai  is  generated. 

T  is  a  2-dimensional  array  of  dimension  kt  X  n  that  is  used  for  temporary  storage.  It 
is  assumed  that  kt  >  m  +  n.  When  L2SLV  terminates,  if  N1  =  n  then  the  unsealed  n  X  n 
covariance  matrix  is  stored  in  the  first  n  rows  and  columns  of  T.  Iterative  improvement  is 
not  performed  on  the  covariance  matrix. 

Error  Return.  IERR  is  an  integer  variable  that  is  set  by  the  routine.  If  no  input  errors  are 
detected  and  the  results  appear  to  be  satisfactory,  then  IERR  is  set  to  0.  Otherwise,  IERR 
is  assigned  one  of  the  following  values: 

IERR  =  1  Either  m,  n,  or  £  is  not  positive. 

IERR  =  2  The  restriction  0  <  m6  <  min{m,n}  is  not  satisfied. 

IERR  =  3  Either  ka  >  m,kb  >  m,kx  >  n,  kr  >  m,  or  kt  >  m+n  is  violated. 

IERR  =  4  WGTS(j')  is  negative  for  some  t  >  me. 

IERR  =  5  Either  WA  =  0  or  E  =  0. 

IERR  =  6  The  rank  of  E  is  less  than  m„. 

IERR  =  7  Iterative  improvement  of  all  the  solutions  xi,  . . . ,  xt  failed  to  con¬ 
verge. 

IERR  =  8  Iterative  improvement  of  one  or  more  solutions  failed  to  converge. 

IERR  =  9  More  than  /i  iterations  of  the  iterative  improvement  procedure 
were  performed  in  computing  some  Xj.  (Here  it  is  assumed  that  a 
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fi  decimal  digit  floating-point  arithmetic  is  being  used,  /i  =  14  for 
the  CDC  6700.) 

10  The  accuracy  of  some  Xj  before  iterative  improvement  was  esti¬ 
mated  to  be  less  than  half  a  decimal  digit. 

1 1  One  or  more  of  the  computed  diagonal  elements  of  the  covariance 
matrix  is  negative.  This  is  due  to  roundoff  error.  Theoretically, 
all  the  diagonal  elements  should  be  nonnegative.  No  evidence  of 
severe  ill-conditioning  was  detected. 

12  One  or  more  of  the  computed  diagonal  elements  of  the  covariance 
matrix  is  negative.  This  is  due  to  roundoff  error.  Theoretically, 
all  the  diagonal  elements  should  be  nonnegative.  The  problem 
appears  to  be  extremely  ill-conditioned. 

When  an  input  error  is  detected  (IERR  =  1,2,  ...  ,6)  then  L2SLV  immediately  terminates. 
If  evidence  of  severe  ill-conditioning  is  detected,  then  IERR  is  set  to  8,9,  or  10  and  com¬ 
putation  of  the  solutions  continues.  If  iterative  improvement  appears  to  converge  for  one 
or  more  of  the  solutions,  then  the  covariance  matrix  is  also  computed  (when  N1  =  n). 
However,  if  iterative  improvement  fails  for  all  the  solutions  xlt  . . .  ,xt  then  IERR  is  set  to 
7  and  the  covariance  matrix  is  not  computed. 

Note.  WK(1),  .. .  ,WK(2£)  should  be  examined  when  severe  ill-conditioning  is  detected. 

Programming.  L2SLV  employs  the  subroutines  DECOM2,  SOLVE2,  SOLVE3,  and  CO- 
VAR.  These  routines  were  written  by  Roy  Wampler  (National  Bureau  of  Standards) .  L2SLV 
is  a  slightly  modified  version  by  A.  H.  Morris  of  the  subroutine  L2B  discussed  in  reference 
(4).  The  algorithm  employed  for  finding  and  iteratively  improving  the  least  squares  solu¬ 
tions  is  described  in  references  (l)-(3).  The  function  SPMPAR  is  also  used. 

References. 

(1)  Bjorck,  Ake,  “Solving  Linear  Least  Squares  Problems  by  Gram-Schmidt  Orthogonal- 
ization,”  BIT 7  (1967),  pp.  1-21. 
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465. 
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ITERATIVE  LEAST  SQUARES  SOLUTION  OF  BANDED  LINEAR 

EQUATIONS 

Given  an  m  x  n  matrix  A,  a  column  vector  b  of  dimension  m,  and  a  real  number  A. 
Let  A  =  ( where  I  is  the  n  x  n  identity  matrix,  and  let  b  =  ( £ ).  The  problem  is  to  find 
a  column  vector  x  of  dimension  n  which  is  a  least  squares  solution  of  Ax  =  b.  If  A  is  stored 
in  band  form  then  the  following  subroutine  is  available  for  solving  this  problem. 

CALL  B LSQ  (m,  n,  A,  ka,  mj,  mu ,  A,  b,  x,  ATOL,BTOL,CONLIM,MXITER, 
IND,ITER,COND,RNORM,XNORM,WK) 

A  is  an  m  x  n  matrix  stored  in  band  form,  mj  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mt  <  m,  0  < 
mu  <  n,  and  ka  >  m.  When  BLSQ  is  called,  an  iterative  procedure  is  used  to  obtain  a 
least  squares  solution  x  of  Ax  =  b.  The  vector  b  is  modified  by  the  routine. 

ATOL  and  BTOL  are  input  arguments  which  specify  the  relative  accuracy  of  A  and  b 
respectively.  For  example,  if  it  is  estimated  that  b  is  accurate  to  k  decimal  digits  then  one 
may  set  BTOL  =  10~fc.  It  is  required  that  ATOL  >  0  and  BTOL  >  0.  If  ATOL  =  0  or 
BTOL  =  0,  then  it  is  assumed  that  A  or  b  is  accurate  to  machine  precision. 

Let  cond(A)  denote  the  condition  number  of  A  relative  to  the  Frobenius  norm.1  In 
each  iteration  of  the  algorithm  being  used,  an  estimate  is  made  of  the  condition  number 
cond(A).  The  estimates  form  a  monotonically  nondecreasing  sequence.  The  input  argument 
CONLIM  is  an  upper  limit  on  cond(A).  If  CONLIM  >  0  then  BLSQ  terminates  when  an 
estimate  of  cond(A)  exceeds  CONLIM.  This  termination  may  be  needed  to  prevent  small 
or  zero  singular  values  of  A  from  coming  into  effect  and  causing  damage  to  the  solution  x. 
CONLIM  may  be  ignored  by  being  set  to  0.  It  is  assumed  that  CONLIM  >  0. 

The  input  argument  MXITER  is  the  maximum  number  of  iterations  that  are  permitted. 
Normally  BLSQ  requires  less  than  4 n  iterations.  The  related  argument  ITER  is  a  variable. 
When  the  routine  terminates  ITER  =  the  number  of  iterations  that  were  performed. 

COND,RNORM,  and  XNORM  are  variables.  When  BLSQ  terminates  COND  =  the 
last  estimate  made  for  cond(A),  RNORM  =  ||Ax  —  5||,  and  XNORM  —  ||x||.2 

WK  is  an  array  of  dimension  2 n  or  larger  that  is  a  work  space  for  the  routine. 

The  equations  Ax  —  b  are  considered  to  be  compatible  if  for  any  least  squares  solution 
x,  ||Ax  —  b\\  =  0.  IND  is  a  variable  that  reports  the  status  of  the  results.  When  BLSQ 
terminates,  IND  has  one  of  the  following  values: 

^ond  (A)  =  ||A||ji'||A+||jr  where  A+  is  the  pseudoinverse  of  A.  Here  ||C7||/’  =  y /ScT  for  any  matrix 
C  —  (c«j)- _ 

2||c||  =  y/Ecf  for  any  vector  c  =  (ci,C3,  ...). 
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IND  =  0  The  solution  is  x  =  0.  No  iterations  were  performed. 

IND  =  1  The  equations  Ax  =  b  are  probably  compatible.  A  solution  x 
has  been  obtained  which  is  sufficiently  accurate,  given  the  values 
ATOL  and  BTOL. 

IND  =  2  The  equations  Ax  =  b  are  probably  not  compatible.  A  least 
squares  solution  x  has  been  obtained  which  is  sufficiently  accu¬ 
rate,  given  the  value  ATOL. 

IND  =  3  An  estimate  GOND  of  cond(A)  exceeds  CONLIM.  The  vector  x  is 
the  most  recent  approximation  of  a  solution  for  Ax  =  b. 

IND  =  4  The  equations  Ax  =  b  are  probably  compatible.  A  solution  x  has 
been  obtained  which  is  as  accurate  as  seems  reasonable  on  this 
machine. 

IND  =  5  The  equations  Ax  =  b  are  probably  not  compatible.  A  least 
squares  solution  x  has  been  obtained  which  is  as  accurate  as  seems 
reasonable  on  this  machine. 

IND  =  6  cond(A)  appears  to  be  so  large  that  there  is  not  much  point  in 
doing  further  iterations.  The  vector  x  is  the  most  recent  approxi¬ 
mation  of  a  solution  for  Ax  —  b. 


IND  =  7  MXITER  iterations  were  performed.  More  iterations  are  needed. 

The  vector  x  is  the  most  recent  approximation  of  a  solution  for 
Ax  =  b. 


Remarks. 

(1)  A  large  estimate  of  the  condition  number  cond(A)  may  be  due  to  rank  deficiency  or  near 
rank  deficiency  of  the  matrix  A.  If  it  is  suspected  that  a  large  estimate  of  cond(A)  has 
occurred  for  this  reason,  then  it  is  recommended  that  CONLIM  be  set  to  a  moderate 
value  such  as  \/e  where  e  is  the  smallest  value  such  that  l+e  >  1  (e  =  2-47  for  the  CDC 
6000-7000  series  computers).  Setting  CONLIM  to  0  is  equivalent  to  setting  CONLIM 
to  e-1. 

(2)  The  vector  b  is  the  only  input  argument  modified  by  the  routine. 

Algorithm.  BLSQ  employs  an  iterative  algorithm  developed  by  Golub  and  Kahan. 

Programming.  BLSQ  calls  the  subroutines  NORMLZ,  BVPRD1,  BTPRD1,  SCOPY,  and 

SSCAL.  The  function  SNRM2  is  also  used.  BSLQ  is  an  adaptation  by  A.  H.  Morris  of  the 

subroutine  LSQR,  written  by  Christopher  C.  Paige  (  McGill  University,  Montreal,  Canada) 

and  Michael  A.  Saunders  (Stanford  University). 

References. 

(1)  Paige,  C.  C.  and  Saunders,  M.  A.,  “LSQR:  An  Algorithm  for  Sparse  Linear  Equations 
and  Sparse  Least  Squares,”  ACM  Trans.  Math  Software  8  (1982),  pp.  43-71. 

(2)  _ ,  “Algorithm  583.  LSQR:  Sparse  Linear  Equations  and  Least  Squares 

Problems,”  ACM  Trans.  Math  Software  8  (1982),  pp.  195-209. 
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ITERATIVE  LEAST  SQUARES  SOLUTION  OF  SPARSE  LINEAR 

EQUATIONS 


Given  an  m  x  n  matrix  A,  a  column  vector  b  of  dimension  m,  and  a  real  number  A. 
Let  A  =  (  )  where  I  is  the  n  x  n  identity  matrix,  and  let  b  =  (  £  ).  The  problem  is  to  find 

a  column  vector  x  of  dimension  n  which  is  a  least  squares  solution  of  Ax  =  6.  If  A  is  sparse 
then  the  following  subroutines  are  available  for  solving  this  problem. 

CALL  SPLSQ(m,  n,  A,  IA,JA,  A, b, x,  ATOL,BTOL,CONLIM,MXITER, 

IND  ,ITER,CO  ND  , RNORM, XNORM,  WK) 

CALL  STLSQ(m,  n,  TA,ITA,JTA,  A,  b,  x,  ATOL ,BTOL ,CONLIM,MXITER, 
IND , ITER, CO  ND  ,RNORM,XNORM,  WK) 

If  SPLSQ  is  called  then  A,  IA,  JA  are  arrays  containing  the  matrix  A  in  sparse  form. 
Otherwise,  if  STLSQ  is  called  then  TA,  ITA,  JTA  are  arrays  containing  the  transpose  matrix 
A4  in  sparse  form.  An  iterative  procedure  is  used  to  obtain  a  least  squares  solution  x  of 
Ax  =  b.  The  vector  b  is  modified  by  the  routines. 

ATOL  and  BTOL  are  input  arguments  which  specify  the  relative  accuracy  of  A  and  b 
respectively.  For  example,  if  it  is  estimated  that  b  is  accurate  to  k  decimal  digits  then  one 
may  set  BTOL  =  10-fc.  It  is  required  that  ATOL  >  0  and  BTOL  >.  0.  If  ATOL  =  0  or 
BTOL  =  0,  then  it  is  assumed  that  A  or  b  is  accurate  to  machine  precision. 

Let  cond (A)  denote  the  condition  number  of  A  relative  to  the  Frobenius  norm.1  In 
each  iteration  of  the  algorithm  being  used,  an  estimate  is  made  of  the  condition  number 
cond(A).  The  estimates  form  a  monotonically  nondecreasing  sequence.  The  input  argument 
CONLIM  is  an  upper  limit  on  cond  (A).  If  CONLIM  >  0  then  the  routines  terminate  when 
an  estimate  of  cond(A)  exceeds  CONLIM.  This  termination  may  be  needed  to  prevent  small 
or  zero  singular  values  of  A  from  coining  into  effect  and  causing  damage  to  the  solution  x. 
CONLIM  may  be  ignored  by  being  set  to  0.  It  is  assumed  that  CONLIM  >  0. 

The  input  argument  MXITER  is  the  maximum  number  of  iterations  that  are  permit¬ 
ted.  Normally  the  routines  require  less  than  in  iterations.  The  related  argument  ITER 
is  a  variable.  When  the  routines  terminate  ITER  =  the  number  of  iterations  that  were 
performed. 

COND,  RNORM,  and  XNORM  are  variables.  When  the  routines  terminate  COND  = 
the  last  estimate  made  for  cond(A),  RNORM  =  ||Ax  —  6]],  and  XNORM  =  ||x||.2 

WK  is  an  array  of  dimension  2 n  or  larger  that  is  a  work  space  for  the  routines. 


1cond  (A)  =  ||A|[jr||A+||/'  where  A+  is  the  pseudoinverse  of  A.  Here  ||C||/-  =  y/'Lc?.  for  any  matrix 
C  =  (c>7). 

3 1| c[|  =  for  any  vector  c  =  (ci,C2,  ...). 
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The  equations  Ax  —  b  are  considered  to  be  compatible  if  for  any  least  squares  solution 
x,  ||  Ax  —  6|j  =  0.  IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routines 
terminate,  IND  has  one  of  the  following  values: 

IND  =  0  The  solution  is  x  =  0.  No  iterations  were  performed. 

IND  =  1  The  equations  Ax  —  b  are  probably  compatible.  A  solution  x 
has  been  obtained  which  is  sufficiently  accurate,  given  the  values 
ATOL  and  BTOL.  _ 

IND  =  2  The  equations  Ax—b  are  probably  not  compatible.  A  least  squares 
solution  x  has  been  obtained  which  is  sufficiently  accurate,  given 
the  value  ATOL. 

IND  —  3  An  estimate  COND  of  cond(A)  exceeds  GONLIM.  The  vector  x  is 
the  most  recent  approximation  of  a  solution  for  Ax  —  b. 

IND  =  4  The  equations  Ax  —  b  are  probably  compatible.  A  solution  x  has 
been  obtained  which  is  as  accurate  as  seems  reasonable  on  this 
machine. 

IND  =  5  The  equations  Ax  —  b  are  probably  not  compatible.  A  least  squares 
solution  x  has  been  obtained  which  is  accurate  as  seems  reasonable 
on  this  machine. 

IND  =  6  cond(A)  appears  to  be  so  large  that  there  is  not  much  point  in 
doing  further  iterations.  The  vector  x  is  the  most  recent  approxi¬ 
mation  of  a  solution  for  Ax  —  b. 

IND  —  7  MXITER  iterations  were  performed.  More  iterations  are  needed. 

The  vector  x  is  the  most  recent  approximation  of  a  solution  for 
Ax  =  b. 

Remarks. 

(1)  A  large  estimate  of  the  condition  number  cond(A)  may  be  due  to  rank  deficiency  or  near 
rank  deficiency  of  the  matrix  A.  If  it  is  suspected  that  a  large  estimate  of  cond(A)  has 
occurred  for  this  reason,  then  it  is  recommended  that  CONLIM  be  set  to  a  moderate 
value  such  as  yfe  where  e  is  the  smallest  value  such  that  1+e  >  1  (e  =  2-47  for  the  CDC 
6000-7000  series  computers).  Setting  CONLIM  to  0  is  equivalent  to  setting  CONLIM 
to  e-1. 

(2)  The  vector  b  is  the  only  input  argument  modified  by  the  routine. 

Algorithm.  SPLSQ  and  STLSQ  employ  an  iterative  algorithm  developed  by  Golub  and 
Kahan. 

Programming.  SPLSQ  and  STLSQ  call  the  subroutines  NORMLZ,  MVPRD1,  MTPRD1, 
SCOPY,  and  SSCAL.  The  function  SNRM2  is  also  used.  SPLSQ  and  STLSQ  are  adaptations 
by  A.  H.  Morris  of  the  subroutine  LSQR,  written  by  Christopher  C.  Paige  (McGill  Univer¬ 
sity,  Montreal,  Canada)  and  Michael  A.  Saunders  (Stanford  University). 

References. 

(1)  Paige,  C.  C.  and  Saunders,  M.  A.,  “LSQR:  An  Algorithm  for  Sparse  Linear  Equations 
and  Sparse  Least  Squares,”  ACM  Trans.  Math  Software  8  (1982),  pp.  43-71. 

(2)  _ _,  “Algorithm  583.  LSQR:  Sparse  Linear  Equations  and  Least  Squares 

Problems,”  ACM  Trans.  Math  Software  8  (1982),  pp.  195-209. 
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MINIMIZATION  OF  FUNCTIONS  OF  A  SINGLE  VARIABLE 


Let  F(x)  be  a  continuous  real-valued  function  defined  for  a  <  x  <  b.  Then  the  following 
subroutine  is  available  for  finding  a  local  minimum  of  F(x). 

CALL  FMIN(jP,  a,  b,  x,  w,  AERR, RERR, ERROR, IND) 

It  is  assumed  that  a  <  b.  FMIN  finds  a  value  x  in  the  interval  [a,  5]  which  is  a  local 
minimum  of  F.  ERROR  and  w  axe  variables.  When  FMIN  terminates,  w  =  F(x)  and 
ERROR  is  the  estimated  maximum  absolute  error  of  x. 

The  input  arguments  AERR  and  RERR  are  the  absolute  and  relative  error  tolerances 
to  be  satisfied.  For  example,  if  k  significant  digit  accuracy  is  desired  then  one  may  set 
RERR  =  10~fc.  It  is  assumed  that  AERR  >  0  and  RERR  >  0.  The  setting  AERR  =  0 
is  equivalent  to  the  setting  AERR  =  10-20,  and  the  setting  RERR  =  0  is  a  request  for 
machine  precision. 

IND  is  a  variable  that  reports  the  status  of  the  results.  END  =  0  if  x  is  found  to  the 
desired  accuracy.  Otherwise,  IND  =  1  when  x  cannot  be  obtained  to  the  desired  accuracy. 
In  this  case,  w  satisfies  the  tolerances  AERR  and  RERR. 

Note.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

Algorithm.  The  golden  section  search  procedure  is  used. 

Programming.  The  function  SPMPAR  is  called.  FMIN  was  written  by  A.  H.  Morris. 
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MINIMIZATION  OF  FUNCTIONS  OF  N  VARIABLES 


Let  f(x)  be  a  real-valued  function  of  n  variables  x  =  {xi,. . . ,  xn)  where  n  >  2.  If  f(x) 
is  twice  continuously  differentiable  then  the  following  subroutine  is  available  for  finding  a 
local  minimum  of  f(x). 

CALL  OPTF(F,  n, RERR, ITER, X, FVAL, IND, WK) 

X  is  an  array  of  dimension  n  and  FVAL  a  variable.  On  input,  X  contains  an  initial 
guess  a  =  (oi,.. .  ,an)  to  a  minimum  of  /.  When  OPTF  terminates,  X  contains  the  final 
estimate  x  =  (ij, . . . ,  xn)  of  a  local  minimum  of  /  and  FVAL  =  f(x). 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F(n,X,FVAL) 

Here  X  is  an  array  of  dimension  n  containing  a  point  x  =  (xlv . . ,  xn),  and  FVAL  is  a 
variable.  F  sets  FVAL  to  the  value  of  the  function  /  at  the  point  x.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

RERR  is  an  input  argument  that  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  accurate  to  k  significant  digits  then  one  may  set 
RERR  =  10“  *.  It  is  required  that  RERR  >  0.  If  RERR  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

When  OPTF  is  called,  Jine  search  iteration  is  performed  to  find  the  local  minimum 
of  /.  ITER  is  a  variable.  On  input,  ITER  is  the  maximum  number  of  iterations  that 
are  permitted.  When  the  routine  terminates,  ITER  =  the  number  of  iterations  that  were 
actually  performed. 

WK  is  an  array  of  dimension  n(n  +  8)  or  larger  that  is  a  work  space  for  the  routine. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  has  one  of  the  following  values: 

IND  =  —  1  (Input  error)  n  <  0. 

IND  =  —2  (Input  error)  n  =  1. 

IND  =  —4  (Input  error)  ITER  <  0. 

IND  =  -5  (Input  error)  Either  RERR  <  0  or  RERR  >  10~4. 

IND  =  1  A  local  minimum  x  was  found.  The  gradient  of  /  at  x  was  con¬ 

sidered  to  be  sufficiently  small. 

IND  =  2  The  steps  taken  became  so  small  that  OPTF  had  to  terminate. 

X  is  probably  a  local  minimum,  but  it  need  not  be  a  local  mini¬ 
mum.  The  algorithm  frequently  requires  exceedingly  small  steps 
to  be  taken,  no  matter  whether  X  is  close  to  or  far  from  a  local 
minimum. 

IND  =  3  A  local  minimum  has  possibly  been  found.  OPTF  could  not  find 

a  point  for  which  /  would  take  a  smaller  value. 

IND  =  4  ITER  iterations  were  performed. 

IND  =  5  The  algorithm  appears  to  be  diverging.  This  generally  occurs 

when  /  is  unbounded  from  below. 
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When  an  input  error  is  detected,  the  routine  immediately  terminates. 

Accuracy  and  Efficiency.  OPTF  is  frequently  extremely  efficient  in  finding  a  value  FVAL 
which  roughly  approximates  a  local  minimum  value  /(io),  but  at  times  it  can  be  quite 
slow  in  obtaining  FVAL  to  greater  precision.  A  rough  approximation  is  often  obtained  in 
20-30  iterations.  If  /(xo)  7^  0  then  FVAL  may  be  accurate  to  4-6  significant  digits  after 
20-30  additional  iterations,  or  FVAL  may  not  be  accurate  to  1  significant  digit  after  several 
hundred  iterations.  4-6  digit  accuracy  is  the  greatest  precision  that  can  be  expected.  In 
general,  it  is  recommended  that  ITER  <  200.  Each  iteration  can  take  considerable  time, 
even  if  the  subroutine  F  is  cheap  to  evaluate. 

Remark.  OPTF  can  be  quite  sensitive  to  the  scaling  of  the  variables  (xi,  . . . ,  x„).  The 
routine  tends  to  operate  more  efficiently  when  the  components  of  a  local  minimum  x  = 
(xi, . . .  ,xn)  are  all  roughly  of  the  same  magnitude.  If  the  components  are  of  considerably 
different  magnitudes  (say  |xi|  »  10-6  and  \x%\  «  103)  then  convergence  may  be  extremely 
slow.  In  such  a  case,  OPTF  attempts  to  rescale  the  variables,  but  the  rescaling  is  not  always 
helpful. 

Algorithm.  The  line  search  algorithm  given  in  pp.  325-327  of  the  reference  is  employed. 
Also,  BFGS  secant  updates  for  the  hessian  are  used. 

Programming.  OPTF  employs  the  subroutines  OPTDRV,  OPCHK1,  OPSTP,  FXDEC, 
SCALEX,  LLTSLV,  FSTOFD,  FSTOCD,  LNSRCH,  SECFAC,  QRUPDT,  and  JROT.  OPTF, 
FXDEC,  and  SCALEX  were  written  by  A.H.  Morris.  The  remaining  subroutines  were  writ¬ 
ten  by  Robert  B.  Schnabel  (University  of  Colorado  at  Boulder)  and  modified  by  A.H.  Morris. 
The  functions  SDOT,  SNRM2,  and  SPMPAR  are  also  used. 

Reference.  Dennis,  J.E.  and  Schnabel,  R.B.,  Numerical  Methods  for  Unconstrained 
Optimization  and  Nonlinear  Equations,  Prentice-Hall,  Englewood  Cliffs,  NJ,  1983. 
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UNCONSTRAINED  MINIMUM  OF  THE  SUM  OF  SQUARES 
OF  NONLINEAR  FUNCTIONS 


Let  /i(i),  . . . ,  fm{x)  be  m  real-valued  functions  of  n  real  variables  x  —  (x1}  . . .  ,x„) 
where  m  >  n.  The  problem  under  consideration  is  to  find  a  point  x  which  minimizes  the 

TO 

function  ^(x)  =  J2  Assume  that  each  /« (x)  is  differentiable  and  that  an  initial 

i=i 

guess  a  =  (ai,  ...  ,an)  to  a  minimum  of  <f>(x)  is  given.  Then  the  following  subroutine  is 
available  for  finding  a  point  which  minimizes  <f>(x). 

CALL  LMDI  FF(F,  m,  n,  X,  FVEC, EPS, TOL, INFO, IWK, WK,  £) 

X  is  an  array  of  dimension  n  and  FVEC  an  array  of  dimension  m.  On  input  X 
contains  the  starting  point  a  =  (a1(  . I.,an).  When  LMDIFF  terminates,  X  contains  the 
final  estimate  x  =  (xi,  . . . ,  xn)  of  a  minimum  of  <f>  and  FVEC  contains  the  values  of  the 
functions  A,. ..,/m  at  the  output  point  in  X. 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F(m,n,X,  FVEC,IFLAG) 

Here  X  is  an  array  of  dimension  n,  FVEC  an  array  of  dimension  m,  and  IFLAG  an 
integer  variable.  The  array^X  contains  a  point  x  =  (ij,  . . .  ,xn).'  Normally  F  evaluates 
the  functions  /1}  ...  ,fm  at  this  point  and  stores  the  results  in  FVEC.  However,  if  x  does 
not  lie  in  the  domain  of  /j,  . . . ,  fm  then  this  cannot  be  done.  In  this  case,  the  argument 
IFLAG  (which  will  have  been  assigned  a  nonnegative  value  by  LMDIFF)  should  be  reset 
by  F  to  a  negative  value.  This  will  signal  LMDIFF  to  terminate.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

EPS  is  an  input  argument  which  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  accurate  to  k  significant  decimal  digits  then  one 
may  set  EPS  =  10-fc.  It  is  required  that  EPS  >  0.  If  EPS  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

TOL  is  an  input  argument  which  specifies  the  desired  accuracy  to  be  attained.  The 
Euclidean  norm  ||x||  =  ^/E,-  x?  is  employed.  If  x  denotes  an  actual  Tniqimmn  of  cj>,  then 
LMDIFF  terminates  when  an  iterate  x  is  generated  for  which  it  is  estimated  that 

(1)  0(x)<(l  +  TOL)2^(x)or 

(2)  ||fl(x-*)||<  TOL -113*11 

is  satisfied.  In  (2)  x  and  x  are  regarded  as  column  vectors,  and  D  is  a  diagonal  matrix 
generated  by  LMDIFF  whose  entries  are  scaling  factors.  For  convenience,  criterion  (1)  is 
called  the  F-convergence  (or  ^-convergence)  test  and  criterion  (2)  is  called  the  x-convergence 
test.  It  is  required  that  TOL  >0.  In  order  for  the  convergence  tests  to  work  properly,  it  is 
recommended  that  TOL  always  be  smaller  than  10— 5. 

IWK  is  an  array  of  dimension  n  and  WK  is  an  array  of  dimension  t.  IWK  and  WK 
are  work  spaces.  It  is  assumed  that  t  >  mn  +  5n  +  m. 
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INFO  is  an  integer  variable  that  reports  the  status  of  the  results.  When  LMDIFF 
terminates,  INFO  has  one  of  the  following  values: 

INFO  <  0  This  occurs  when  the  user  terminates  the  execution  of  LMDIFF  by 
resetting  the  argument  IFLAG  in  the  subroutine  F  to  a  negative 
value.  Then  INFO  =  the  negative  value  of  IFLAG. 

INFO  =  0  (Input  error)  1  <  n  <  m,  EPS  >  0,  TOL  >  0,or  t  >  mn  +  5n  +  m 
is  violated. 

INFO  =  1  The  E-convergence  test  has  been  satisfied. 

INFO  =  2  The  x-convergence  test  has  been  satisfied. 

INFO  =  3  The  E-convergence  and  x-convergence  tests  have  been  satisfied. 

INFO  =  4  The  gradient  of  tj>  is  0  at  point  A. 

INFO  =  5  The  number  of  calls  to  the  subroutine  F  has  reached  or  exceeded 
200(n  +  1). 

INFO  =  6  TOL  is  too  small.  No  further  reduction  in  the  value  of  <f>(x)  is 
possible. 

INFO  =  7  TOL  is  too  small.  No  further  improvement  in  the  accuracy  of  X 
is  possible. 

When  LMDIFF  terminates,  if  INFO  =£  0  then  X  contains  the  final  iterate  that  was  gener¬ 
ated.  Also,  if  INFO  >  1  then  FVEC  contains  the  values  of  the  functions  /i,  . . . ,  /»  at  this 
iterate.  If  INFO  =  4  then  A  should  be  examined  very  closely.  The  gradient  of  <j>  can  be  0 
when  A  is  a  local  minimum  or  maximum,  or  when  A  is  a  saddle  point.  If  INFO  =  5  then 
it  may  (or  may  not)  be  helpful  to  continue  the  procedure  by  recalling  LMDIFF  with  the 
current  point  in  A  as  the  new  starting  point.  Since  TOL  is  a  relative  tolerance,  this  setting 
can  occur  when  <£(0)  =  0. 

Algorithm.  A  modified  form  of  the  Levenberg-Marquardt  algorithm  is  employed. 

Programming.  LMDIFF  is  a  slightly  modified  version  of  the  MINPACK-1  subroutine 
LMDIF1.  The  MINPACK-1  subroutines  LMDIF,  SPMPAR,  ENORM,  FDJAC2,  LMPAR, 
QRFAC,  and  QRSOLV  are  employed.  The  subroutines  were  written  by  Jorge  J.  More, 
Burton  S.  Garbow,  and  Kenneth  E.  Hillstrom  (Argonne  National  Laboratory). 

References. 

(1)  More,  J.  J.,  Garbow,  B.  S.,  and  Hillstrom,  K.  E.,  User  Guide  for  MINPACK-1, 
Argonne  National  Laboratory  Report  ANL-80-74,  Argonne,  Illinois,  1980. 

(2)  More,  J.  J.,  “The  Levenberg-Marquardt  Algorithm:  Implementation  and  Theory,” 
Numerical  Analysis ,  G.  A.  Watson  (ed.),  Springer- Verlag,  1977. 


354 


LINEAR  PROGRAMMING 


Let  A  =  (a,y)  be  an  m  x  n  matrix,  B  an  array  containing  ,  6m,  and  C  an  array 

containing  ci,  . . . , c„  where  a,y,  bi,Cj  are  real.  Consider  the  problem  of  finding  nonnegative 

values  xi,  . . .  ,xn  which  maximize  or  minimize  the  function  C\X !  H - +  cnxn  subject  to 

the  constraints: 

alllH - H  Oln*n{<,  =,  >}&1 

aml^l  “h  * "  *  “h 

In  each  constraint 

0,1*1  +"-  +  a,na:„{<,=J>}6i 

only  one  of  the  relations  <,=,>  is  used,  but  the  relation  may  vary  from  constraint  to 
constraint.  The  following  subroutines  are  available  for  solving  this  problem. 

CALL  SMPLX(A,  B,  C, ka,  m,  n,  IND,IBASIS,X>,  ITER,MXITER, 
NUMLE,NUMGE,BI,WK,IWK) 

CALL  SSPLX(TA,ITA,JTA,  B,  C,  m,  n,  IND, IBASIS,  X,  z,  ITER, MXITER, 
NUMLE,NUMGE,BI,WK,IWK) 

It  is  assumed  that  m  >  2,n  >  2,  and  that  each  b*  >  0.  If  SMPLX  is  called  then  ka  is 
the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  Otherwise, 
if  SSPLX  is  called  then  TA,  ITA,  JTA  are  arrays  containing  the  transpose  matrix  At  in 
sparse  form. 

The  constraints  a,iXi  +  ■  ■  *  +  o,nxn{<,  =,>}&<  are  assumed  to  be  ordered  so  that  the 
<  constraints  are  followed  by  the  >  constraints,  and  the  =  constraints  come  last.  NUMLE 
and  NUMGE  have  the  values: 

NUMLE  =  the  number  of  <  constraints. 

NUMGE  =  the  number  of  >  constraints. 

It  is  assumed  that  NUMLE  >  0,  NUMGE  >  0,  and  NUMLE  +  NUMGE  <  m. 

When  SMPLX  or  SSPLX  is  called,  the  routine  attempts  to  maximize  Eycyiy  subject 
to  the  constaints.  A  modified  form  of  the  primal  simplex  algorithm  is  employed.  Frequently 
the  procedure  requires  less  than  5m  iterations  to  perform  the  task.  The  argument  MXITER 
has  the  value: 

MXITER  =  the  maximum  number  of  iterations  that  may  be  performed. 

This  argument  is  provided  by  the  user.  The  related  argument  ITER  is  a  variable  that  is 
set  by  the  routine.  When  the  routine  terminates,  ITER  has  for  its  value  the  number  of 
iterations  that  were  performed. 

IND  is  a  variable  and  IBASIS  an  array  of  dimension  m.  IBASIS  contains  the  indices 
i  of  the  current  basic  variables  x,-,  and  IND  is  used  for  input/output  purposes.  On  in¬ 
put  IND  is  normally  set  by  the  user  to  0.  If  IND  =  0  then  the  routine  selects  its  own 
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beginning  basis  and  stores  the  appropriate  indices  in  IBASIS.  [The  remainder  of  this  parar 
graph  may  be  skipped  by  anyone  not  acquainted  with  the  simplex  algorithm.]  If  the  user 
wishes  to  use  his  own  beginning  basis,  then  IND  must  be  set  to  1  and  the  indices  of 
the  initial  basic  variables  stored  in  IBASIS.  It  is  not  required  that  the  initial  basis 
be  selected  so  that  the  basic  variables  are  nonnegative.  The  initial  basic  variables  may 
be  original,  slack,  surplus,  or  artificial  variables.  Slack  and  surplus  variables  are  automat¬ 
ically  provided  for  the  <  and  >  constraints,  and  artificial  variables  for  the  =  constraints. 
The  routine  defines  xn+i  to  be  the  slack,  surplus,  or  artificial  variable  for  the  it>l  constraint 
H  1-  a,'rjZ„{<,  =,  >}&,-.  If  IND  =  0  then  the  slack,  surplus,  and  artificial  variables 
are  the  initial  basic  variables  that  are  employed. 

On  output  IND  reports  the  status  of  the  results.  The  routine  assigns  IND  one  of  the 
following  values: 

IND  =  0  The  problem  was  solved. 

IND  =  1  The  problem  has  no  solution. 

IND  =  2  MXITER  iterations  were  performed.  More  iterations  are  needed. 

IND  =  3  Sufficient  accuracy  cannot  be  maintained  to  solve  the  problem. 

IND  =  4  The  problem  has  an  unbounded  solution. 

IND  =  5  An  input  error  was  detected.  (See  below) 

IND  =  6  A  possible  solution  was  obtained.  The  routine  is  not  certain  if  the 
solution  is  correct. 

X  is  an  array  of  dimension  n  +  NUMLE  +  NUMGE  and  z  is  a  variable.  If  IND  =  0  or 
IND  =  6,  then  z  has  for  its  value  the  maximum  value  obtained  for  EjCjXj  and  X  contains 
the  values  obtained  for  the  original,  slack,  and  surplus  variables.  If  IND  ^  5  then  IBASIS 
contains  the  indices  of  the  basic  variables  currently  in  effect  when  the  routine  terminates. 

BI  is  an  array  of  dimension  m2  that  is  used  for  storing  the  inverse  of  the  basis  matrix. 
The  order  of  the  column  vectors  of  the  basis  matrix  corresponds  to  the  order  of  the  basic 
variables  given  in  IBASIS.  If  IND  #  3, 5  on  output  then  BI  contains  the  inverse  of  the  basis 
matrix  currently  in  effect  when  the  routine  terminates. 

WK  is  an  array  of  dimension  2m  or  larger,  and  IWK  is  an  array  of  dimension  2m  +  n 
or  larger.  WK  and  IWK  are  work  spaces. 

Input  Errors.  IND  =  5  occurs  on  output  when  one  of  the  following  conditions  is  violated: 

(1)  n  >  2  and  ka  >  m  >  2. 

(2)  NUMLE  +  NUMGE  <  m. 

(3)  Each  bi  >  0. 

(4)  The  basis  matrix  specified  by  the  user  in  IBASIS  (when  IND  =  1  on  input)  is  nonsin¬ 
gular  and  sufficiently  well  conditioned  so  that  its  inverse  can  be  computed. 

Remarks. 

(1)  A,  B,  C,TA,ITA,JTA  are  not  modified  by  the  routines. 

(2)  The  routines  maximize  E  jCjXj.  This  function  can  be  minimized  by  maximizing  £,-(— cy) Xj 
and  then  changing  the  sign  of  the  result. 
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(3)  SMPLX  and  SSPLX  generate  the  same  results.  For  efficiency,  SSPLX  should  be  used 
when  A  is  sparse. 

Algorithm.  A  three  step  procedure  is  used.  The  first  step  eliminates  the  negative  variables. 
Then  phases  (l)  and  (2)  of  the  primal  simplex  algorithm  are  invoked.  Negative  variables 
are  eliminated  as  follows:  Let  xBi,  . . . ,  xBm  be  the  basic  variables  and  y,y  the  components 
of  the  simplex  tableau. 

(1)  Compute  dj  =  E't/iy  for  each  nonbasic  variable  Xj  where  the  sum  S'  is  for  all  *  where 
xgi  <  0.  If  all  dj  >  0  then  the  problem  has  no  feasible  solution.  Otherwise,  select  k  so 
that  dk  =  mirijdj.  Then  Xk  is  the  variable  to  be  made  basic. 

(2)  If  x gj  >  0  and  yyt  >  0  for  some  j  then  go  to  (3).  Otherwise,  select  a  negative  variable 
xgT  to  become  nonbasic  where  xBr/yr k  =  ma x{xBj/yjk  ■  xBj  <  0  and  yjk  <  0}.  Then 
update  the  basis  and  go  to  (5). 

(3)  Compute  e  =  xmn{xBj/ yjk  '■  xBj  >  0  and  yjk  >  0}  and  check  if  a  negative  variable 
xBj  exists  that  satisfies  the  conditions: 

(*)  yjk  <  0  and  e  >  xBjjyjk 

If  such  a  variable  exists  then  go  to  (4).  Otherwise,  select  a  nonnegative  variable  xBr  to 
become  nonbasic  where  yrk  >  0  and  xBr/yrk  =  e.  Then  update  the  basis  and  go  to  (l). 

(4)  Select  a  negative  variable  xBr  to  become  nonbasic  where  xBrfyrk  =  ma x{xBjjyjk  : 
xBj  <  0  and  xBj  satisfies(*)}.  Then  update  the  basis  and  go  to  (5). 

(5)  Check  if  there  are  any  remaining  negative  variables.  If  not,  then  we  are  finished. 
Otherwise  go  to  (1). 

Programming.  SMPLX  and  SSPLX  employ  the  subroutines  SMPLX1,  SSPLX1,  and 
CROUT1.  These  routines  were  written  by  A.  H.  Morris.  The  function  SPMPAR  is  also 
used. 
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THE  ASSIGNMENT  PROBLEM 


Let  C  =  (c,y)  be  an  n  x  n  matrix  (the  cost  matrix).  The  problem  under  consideration 

n  n 

is  to  find  an  n  x  n  matrix  x  =  (x,y)  which  minimizes  T  =  E  E  c*jxij  and  satisfies: 

t=ij=i 

(1)  E  *ij  =  1  for  j  =  1,  ...,n 

i= 1 

(2)  E  xij  =  l  for  t  =  1,  . . . ,  n 
1=1 

(3)  Each  Xij  =  0  or  1 

Each  x  which  satisfies  (l)— (3)  is  called  an  assignment.  For  each  such  x,  from  (1)  and  (3) 
we  note  that  for  each  j  there  exists  a  unique  integer  jt(j)  such  that  xx^j  =  1.  Also,  (2) 
and  (3)  assert  that  tt  is  a  permutation  of  {1,  Conversely,  for  any  permutation  jt 

there  corresponds  an  assignment  x  defined  by  =  1  and  x,y  =  0  for  *  ^  ir (j).  Thus, 

n 

the  problem  is  to  find  a  permutation  tt  of  {1,  . . . ,  n}  which  minimizes  T  =  E  cr(j)  j •  The 

i=1 

following  subroutine  is  available  for  solving  this  problem  when  all  c,y  are  integers. 

CALL  ASSGN(n,  C,  JC, T, IWK,IERR) 

C  is  a  2-dimensional  integer  array  of  dimension  n  x  (n  +  1),  JC.an  integer  array  of 
dimension  n,  and  T  an  integer  variable.  It  is  assumed  that  ti  >  2  and  that  the  first  n 
columns  of  C  contain  the  cost  matrix  (c,y).  [The  (n+  l)ai  column  of  C  is  a  work  space  for 
the  routine.]  When  ASSGN  is  called,  the  desired  permutation  x  is  obtained  and  the  values 
x(l),  . .  .,x(n)  stored  in  JC.  Also  T  is  assigned  the  minimized  value  Eyc^yjj. 

IWK  is  an  array  of  dimension  7n  +  2  or  larger  that  is  a  work  space  for  the  routine. 

IERR  is  a  variable  that  is  set  by  the  routine.  If  JC  and  T  are  obtained  then  IERR  is 
assigned  the  value  0.  Otherwise,  if  the  problem  cannot  be  solved  because  of  integer  overflow, 
then  IERR  =  1. 

Remarks. 

(1)  C  is  destroyed  by  the  routine. 

(2)  ASSGN  minimizes  T  =  SycT(yj  y.  This  function  can  be  maximized  by  minimizing 
Ey(-cx(y)  y)  and  then  changing  the  sign  of  the  result. 

Programming.  ASSGN  calls  the  subroutine  ASSGN1.  ASSGN1  was  written  by  Giorgio 
Carpaneto  and  Paolo  Toth  (University  of  Bologna,  Italy),  and  modified  by  A.  H.  Morris. 
The  function  IPMPAR  is  also  used. 

Reference.  Carpaneto,  G.,  and  Toth,  P.,  “Algorithm  548,  Solution  of  the  Assignment 
Problem,”  ACM  Trans.  Math  Software  6  (1980),  pp.  104-111. 
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0-1  KNAPSACK  PROBLEM 

Given  n  >  2  items,  each  having  a  profit  pj  >  0  and  weight  Wj  >  0,  and  m  >  1 
containers  (knapsacks),  each  having  a  capacity  ki  >  0.  Let  z,-y  =  1  if  item  j  is  assigned  to 
knapsack  ».  Otherwise,  let  =  0.  Then  the  problem  is  to  find  an  assignment  x,-y  of  the 

rrv  n 

items  to  the  knapsacks  which  maximizes  a  =  E  EPj  xij  subject  to 

n  ’'=lj'=1 

(1)  E  wj  x*j  <  ki  for  *  =  1,  ,  m,  and 

j=l 

(2)  E  xij  <  1  for  i  =  1,  . . . ,  n. 

«=i 

Condition  (2)  states  that  each  item  may  be  assigned  to  a  (single)  knapsack  or  be  rejected. 
It  can  be  assumed,  without  loss  of  generality,  that 

(a)  the  knapsacks  are  ordered  so  that  k\  <  •  •  •  <  km , 

(b)  min{u;i,. . . ,  wn  }  <  k\, 

(c)  max{  toi,. . . ,  wn  }  <  km,  and 

(d)  EyLi  ^j  >  kn. 

Then  the  following  subroutine  is  available  for  solving  this  problem  when  all  py,  Wj,  and  ki 
are  positive  integers. 

CALL  MKP(n,  m,  P,  W,  K,NBCK,L, cr, TEMP, ITEMP,NUM) 

P  and  W  are  integer  arrays  containing  pi,. ..,p„  and  wi} and  K  an  integer 
array  containing  k\,...,km.  L  is  an  integer  array  of  dimension  n  or  larger,  and  a  an  integer 
variable.  When  MKP  is  called,  if  no  input  errors  are  detected  then  the  maximum  value  for 
a  is  obtained.  Also,  L(j)  =  t  if  item  j  has  been  assigned  to  knapsack  i  (j  =  1,  . . .  ,n),  and 
L(j)  =  0  if  item  j  does  not.  appear  in  the  solution  (i.e.,  if  Xi}-  =  •  *  •  =  zny  =  0). 

A  depth-first  tree  search  employing  backtracking  is  used.  If  no  bound  is  placed  on 
the  number  of  back  tracks  that  may  be  performed,  then  the  exact  maximum  a  is  assured. 
However,  if  the  number  of  back  tracks  must  be  restricted,  then  only  an  approximation 
to  the  maximum  may  be  obtained.  The  argument  NBCK  is  available  for  limiting  the 
backtracking.  NBCK  is  a  variable.  On  input,  if  NBCK  =  -1  then  no  restrictions  are 
placed  on  the  backtracking.  Otherwise,  if  NBCK  #  -1,  then  it  is  assumed  that  NBCK 
is  the  maximum  number  of  back  tracks  that  are  permitted.  When  the  routine  terminates, 
NBCK  =  the  number  of  back  tracks  that  were  actually  performed. 

TEMP  is  a  real  array  of  dimension  n  or  larger,  and  ITEMP  an  integer  array  of  dimen¬ 
sion  NUM.  It  is  assumed  that  NUM  >  5m  +  14n  +  4mn  +  3.  TEMP  and  ITEMP  are  work 
spaces  for  the  routine.  It  should  be  noted  that  TEMP  is  the  only  argument  of  MKP  that 
is  not  of  integer  type. 

Error  return.  If  an  input  error  is  detected  then  a  is  set  to  one  of  the  following  values: 
a  —  —  1  ifm<lorn<2. 
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2  if  some  Pj,Wj,  or  ki  is  not  positive. 

3  if  min{u>i,  . . . ,  tun}  >  i.e.,  if  a  knapsack  cannot  contain  any 

item. 

4  if  max{t»i,'. . . ,  wn}  >  km ;  i.e.,  if  an  item  cannot  fit  in  any  knap¬ 
sack. 

5  if  Ejttfy  <  km\  i.e.,  if  knapsack  m  can  contain  all  the  items. 

7  if  the  knapsacks  are  not  ordered  so  that  &i  <  ■  •  •  <  fcm. 

8  if  NUM  <  5m  +  14n  +  4mn  +  3. 

Backtracking.  For  NBCK  =  —  1,  the  time  required  for  finding  the  exact  maximum  depends 
primarily  on  the  value  of  m,  and  can  increase  quite  dramatically  for  very  small  increases  in 
the  value  of  m.  It  is  recommended  that  this  setting  never  be  used  when  m  >  10.  Instead, 
if  m  >  10  then  a  setting  of  NBCK  <  50  frequently  suffices. 

Programming.  MKP  employs  the  subroutines  MKP1,  SIGMA1,  PI1,  PARC,  SKNP,  and 
SKNP1.  The  interface  subroutine  MKP  was  written  by  A.H.  Morris.  The  remaining  subrou¬ 
tines  were  written  by  Silvano  Martello  (University  of  Bologna)  and  Paolo  Toth  (University 
of  Florence)  and  modified  by  A.H.  Morris.  The  subroutine  RISORT  is  also  used. 

Reference.  Martello,  S.  and  Toth,  P.,“ Algorithm  632.  A  Program  for  the  0-1  Multiple 
Knapsack  Problem,”  ACM  Trans.  Math  Software  11  (1985),  pp.  135-140. 
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INVERSION  OF  THE  LAPLACE  TRANSFORM 


Let  /(f)  be  a  complex- valued  function  that  is  continuous  for  t  >  0  except  possibly  at 
a  countable  set  of  values  t*,  having  no  finite  limit  points.  Then  for  complex  z  the  Laplace 
transform  F (z)  of  /(f)  is  defined  by 

F(z)=  e-*mdt 
Jo 

when  the  integral  converges.  If  the  integral  converges  for  Re(z)  >  c  but  does  not  exist  for 
Re(z)  <  c,  then  c  is  called  the  abscissa  of  convergence  of  F(z).  If  J0°°  \f(i)\e~at  dt  <  oo 
for  some  real  constant  a,  then  F(z)  is  analytic  for  all  z  where  R e(z)  >  a.  Also,  for  any  point 
t  for  which  /(f)  is  continuous  and  sufficiently  well-behaved,  the  value  /(f)  can  be  obtained 
from  F  by  the  inversion  formula 

i  ra+iT 

=  («• = v=T> 

t-kx>  Ja_iT 

for  any  a  >  a.  If  /(f)  is  real  for  t  >  0,  then  F(z)  =  F(z).  Given  a  transform  F(z)  where 
F(z)  =  F(z),  then  the  following  subroutine  is  available  for  computing  /(f)  for  t  >  0. 

CALL  L  A I N  V  (MO ,  FUN  ,f ,  AERR,RERR  ,Y,  c,  ERROR,  NUM,IERR) 

It  is  assumed  that  F(z)~=  F(z).  The  argument  FUN  is  the  name  of  a  user  defined 
subroutine  for  computing  F (z).  FUN  has  the  format: 

CALL  FUN(ar,  y,  A,B) 

A  and  B  are  variables.  For  real  arguments  x  and  y,  A  and  B  are  assigned  the  values 
A  =  Re[.F(x  +  t'y)]  and  B  =  Im[F(x  +  ty)j.  FUN  must  be  declared  in  the  calling  program 
to  be  of  type  EXTERNAL. 

IERR  is  a  variable  that  is  used  both  for  input  and  output  purposes.  If  IERR  >  0  on 
input  then  it  is  assumed  that  the  abscissa  of  convergence  is  known  and  that  c  =  the  abscissa 
of  convergence.  Otherwise,  if  IERR<  0  then  the  abscissa  of  convergence  must  be  computed. 
In  this  case,  c  is  a  variable.  LAINV  sets  c  to  the  value  that  is  obtained  for  the  abscissa  of 
convergence. 

MO  is  an  integer  which  specifies  the  search  procedure  to  be  used  for  finding  the  abscissa 
of  convergence  c  when  IERR  <  0  on  input.  A  two-pass  procedure  is  employed  when  MO 
=  0,  and  a  one-pass  procedure  when  MO  ^  0.  When  all  the  singularities  of  F(z)  are  real, 
the  two-pass  procedure  (MO  =  0)  is  almost  always  considerably  more  efficient.  Conversely, 
if  none  of  the  singularities  of  F(z)  are  real,  or  if  F(z)  has  complex  singularities  that  are  to 
the  right  of  real  singularities,  then  the  one-pass  procedure  (MO  ^  0)  is  more  efficient. 

It  is  assumed  that  t  >  0  and  that  Y  is  a  variable.  When  LAINV  is  called  Y  is  set  to 
the  value  obtained  for  /(t). 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used  in  computing 
F(t)  (AERR  >  0  and  RERR  >0).  If  one  wants  accuracy  to  k  significant  digits  then  set 
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RERR  =  10  *.  If  RERR  =  0  then  it  is  assumed  that  f[t )  is  to  be  computed  to  machine 
accuracy.  LAINV  attempts  to  find  a  value  Y  which  satisfies  |Y  -  f\  <  max{  AERR,  RERR- 

mb 

ERROR  and  NUM  are  variables  that  are  set  by  the  routine.  When  LAINV  terminates, 
ERROR  is  a  rough  estimate  of  the  absolute  error  | Y  -  f(t) |  and  NUM  is  the  number  of 
calls  that  were  made  to  the  subroutine  FUN. 

When  LAINV  terminates,  IERR  reports  the  status  of  the  results.  IERR  is  assigned 
one  of  the  following  values: 

IERR  =  0  Y  was  obtained  to  the  desired  accuracy. 

IERR  =  1  Y.  was  obtained,  but  it  may  not  be  accurate  because  of  inaccuracy 
in  the  computation  of  c.  This  setting  occurs  only  when  IERR  <  0 
on  input. 

IERR  =  2  Y  could  not  be  obtained,  possibly  because  too  much  accuracy  was 
requested.  Increase  AERR  and  RERR,  and  rerun  the  problem. 

IERR  =  3  Y  could  not  be  obtained,  possibly  because  of  inaccuracy  in  the 
computation  of  c  or  too  much  accuracy  was  requested.  Increase 
AERR  and  RERR,  and  rerun  the  problem.  This  setting  occurs 
only  when  IERR  <  0  on  input. 

IERR  =  4  (Input  error)  The  argument  t  is  not  positive.  Y  and  ERROR  are 
assigned  the  values  0  and  1. 

IERR  =  5  The  abscissa  of  convergence  c  could  not  be  found  int  he  interval 
[-104,104].  Y,  c,  and  ERROR  are  assigned  the  values  0,  0,  and 
1.  This  setting  occurs  only  when  IERR  <  0  on  input. 

IERR  =  6  The  argument  t  is  too  large  for  /(f)  to  be  computed.  Y  and 
ERROR  are  assigned  the  values  0  and  1. 

Remarks. 

(1)  Accuracy  decreases  when  t  is  near  a  discontinuity  of  /(f). 

(2)  The  calculation  may  lose  accuracy  or  fail  when  F(t)  is  oscillatory. 

Algorithm.  Given  c,  /(f)  is  computed  by  a  modification  of  the  subroutine  DLAINV  devel¬ 
oped  by  R.  Piessens  and  R.  Huysmans,  where  the  real  Wynn  e-algorithm  has  been  replaced 
with  the  complex  Wynn  e-algorithm. 

When  IERR  <  0,  c  is  calculated  by  the  subroutine  ABCON  or  the  subroutine  AB- 
CON1.  In  ABCON,  which  is  a  two-pass  search  procedure,  the  abscissa  xi  of  the  rightmost 
singularity  in  the  strip  -104  <  x  <  104,  |y|  <  .01  is  first  determined.  Then  the  abscissa  of 
the  rightmost  singularity  in  the  half-plane  Re(z)  >  x\  is  found.  In  ABCON1  these  calcula¬ 
tions  are  combined  into  a  single-pass  procedure. 

In  ABCON  and  ABCON1,  the  function  F(z)/(z-|-|xi|-)-l)  is  integrated  along  paths  C\ 
and  C2  defined  as  follows:  C\  is  the  straight  line  segment  from  (xi,0)  to  (ii,  .01),  followed 
by  the  straight  line  segment  from  (x^.Ol)  to  (oo,.01),  and  C2  is  the  straight  line  segment 
from  (x1(oo)  to  (xj.O),  followed  by  the  straight  line  segment  from  (xi,0)  to  (oo,0).  The 
integral  along  C\  vanishes  if  no  singularity  lies  to  the  right  of  Xj  in  the  strip  |yj  <  .01, 
and  the  integral  along  C2  vanishes  if  no  singularity  lies  in  Re(z)  >  ij.  Otherwise,  these 
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integrals  are  nonzero  in  most  applications.  Simpson’s  rule  suffices  for  integrating  along  the 
finite  line  segment  from  (xi,0)  to 


Example.  Let  F{z )  =  1/(1  +  2J),  in  which  case  f(t)  =  sint.  The  following  code  may  be 
used  for  computing  f(t)  at  t  —  1, 1.1, 1.2, . . . ,  1.9  and  storing  the  results  in  the  array  W . 

REAL  W(10) 

EXTERNAL  FT 
C 

AERR  =  l.E-30 
RERR  =  l.E-12 
IERR  =  -1 
T  =  1.0 
DO  10  I  =  1,10 

CALL  LAINV  (1,  FT,  T,  AERR,  RERR,  W(I),  C,  ERR,  N,  IERR) 

IF  (IERR  .GT.  1)  STOP 
T  =  T  +  0.1 
10  CONTINUE 

Here  FT  may  be  defined  by: 

SUBROUTINE  FT(X,  Y,  A,  B) 

COMPLEX  Z,W 
C  ' 

Z  =  CMPLX(X,Y) 

W  =  1.0/(1.0  +  Z**2) 

A  =  REAL(W) 

B  =  AIMAG(W) 

RETURN 

END 

Programming.  LAINV  employs  the  subroutines  ABCON,  ABCON1,  SRCH,  ACOND, 
XCOND,  LAIN VI,  CQEXT,  QAGI1,  QAGIE1,  QELG,  QK15I1,  QPSRT,  CDIVID  and 
functions  ACONDF,  ACONDG,  XCONDX,  XCONDY,  SPMPAR,  EXPARG.  LAINV  and 
ABCON  were  written  by  Andrew  H.  van  Tuyl  (NSWC)  and  modified  by  A.H.  Morris.  AB- 
CON1  was  written  by  A.H.  Morris.  LAINV1  was  written  by  Robert  Piessens  and  Rudi 
Huysmans  (University  of  Leuven,  Herverlee,  Belgium)  and  modified  by  Andrew  van  Tuyl. 
QAGI1  is  a  modification  of  QAGI  by  Andrew  van  Tuyl  and  A.H.  Morris. 

Reference.  Piessens,  R.  and  Huysmans,  R.,  "Algorithm  619.  Automatic  Numerical  Inver¬ 
sion  of  the  Laplace  Transform,”  ACM  Trans.  Math  Software  10  (1984),  pp.  348-353. 
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FAST  FOURIER  TRANSFORM 


Let  n  be  a  positive  integer  and  0y  —  2 xj/n  for  j  =  0, 1, . . .  ,n  -  1.  For  any  complex 

n— 1  _ 

valued  functions  /  and  g  defined  on  the  points  0y  let  (f,g)  =  £  f{8j)  <?(0y).  Then  (f,g)  is 

i=o 


an  inner  product  when  /  and  g  are  regarded  as  functions  defined  only  on  9j.  Also  (j  = 
0, 1,  . . . ,  n  —  1)  form  an  orthogonal  set  of  functions  where  each  has  norm  yfn.1  Thus,  if 


n— 1 


/  is  a  function  that  is  approximated  by  f(9)  -  £  cye’i9  then  each  cy  =  ^(/(0),eij*).  The 

3=0 

mapping  /(0y)  *-+  cy  given  by 


Cj=^nzm)e-2xijk/ 

n  k=o 

is  called  the  discrete  Fourier  transform  and  its  inverse 


f(*j)  =  E1  cke2xi^n 

k=  0 

the  inverse  discrete  Fourier  transform.  The  followmg  subroutines  are  available  for  com¬ 
puting  these  transforms. 

CALL  FFT (C,  n,  l,  IERR) 

CALL  FFT1  (A,  IERR) 

Let  cy  =  ay  +  ibj(j  =  0, 1,  . . . ,  n  —  1)  be  the  data  to  be  transformed.  If  FFT  is  called 
then  C  is  a  complex  array  containing  co.cj,  ...,cn_!  (where  C(j  +  1)  =  cy  for  j  <  n). 
Otherwise,  if  FFT1  is  called  then  A  and  B  are  real  arrays  containing  ao,ai,  . . .  ,an_j  and 
bo,bi,  ,  6n_i  respectively. 

The  argument  t  may  have  the  values  1  or  -1,  and  IERR  is  a  variable.  When  FFT  or 
FFT1  is  called,  if  there  are  no  input  errors  then  IERR  is  set  to  0  and 

n—  1 

Cy  =  ^  CkeiTUjk/n 
k= 0 


is  computed.  The  results  cy  =  ay  +  *Sy  replace  the  original  data  cy  =  ay  +  ibj  in  C  (or  A 
and  B). 

Restrictions  on  the  argument  n.  When  FFT  and  FFT1  are  called,  n  is  factored  by  the 
routine  into  its  prime  factors.  It  is  assumed  that  the  largest  prime  factor  of  n  is  <  23.  If 
n  =  fi2n  where  n  is  the  square  free  portion  of  n,  then  it  is  further  assumed  that  n  <  210 
whenever  n  is  a  product  of  two  or  more  primes. 

1  Throughout  this  section  t  =  V- 1. 
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Error  Return.  If  an  input  error  is  detected  then  IERR  is  set  as  follows: 

IERR  =  I  if  n  <  1. 

IERR  =  2  if  n  has  too  many  factors. 

IERR  =  3  if  n  has  a  prime  factor  greater  than  23  or  the  square  free  portion 
of  n  is  greater  than  210. 

IERR  =  4  if  £  #  ±1. 

The  setting  IERR  =  2  can  occur  only  when  n  >  4251528. 

Remark.  The  complex  array  C  is  interpreted  by  FFT  as  a  real  array  of  dimension  2n.  If 
this  association  is  not  permitted  by  the  FORTRAN  being  employed  then  use  FFT1. 

Programming.  FFT  and  FFT1  are  interface  routines  for  the  subroutine  SFFT,  which  was 
written  by  Richard  C.  Singleton  (Stanford  Research  Institute). 

Reference.  Singleton,  R.  C.,  “An  Algorithm  for  Computing  the  Mixed  Radix  Fast  Fourier 
Transform,”  IEEE  Trans.  Audio  and  Electroacoustics,  vol.  AU-17  (1969),  pp.  93-103. 
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MULTIVARIATE  FAST  FOURIER  TRANSFORM 


Let  ni,  . . . ,  nm  be  positive  integers.  For  any  J  =  ( ju  . . .  ,jm)  where  j„  =  0, . . . ,  nv  -  1 
=  !»•••) let  6j  denote  the  point  (23rji/»i,  . . . ,  2xjm/nm).  Also,  for  any  complex 
valued  fimctions  /  and  g  defined  on  the  points  9j  let  (f,g)  =  S jf{9j)  g{9j).  Then  (f,g) 
is  an  inner  product  when  /  and  g  are  regarded  as  functions  defined  only  on  9j.  Also  the 
functions  <f>j[9)  =  exp(»ji01)  •  •  •  exp(ijm0m)  form  an  orthogonal  set  where  each  <j>j  has  the 
norm  y/n\  •  •  -n^.1  Thus,  if  /  is  a  function  that  is  approximated  by  /  =  Y,jcj<j>j  then  each 
CJ  =  «!•••■>»  The  mapping  f((f>j)  >-+  cj  given  by 

c3  =  Wl..X.Wm  Ek  f{.0K)  exp(-2xtj1fcl/ni)  •  -  -exp(-2 xijmkm/nm) 

is  called  the  discrete  multivariate  Fourier  transform  and  its  inverse 

f{&j)  ~  exp(2x*j'ifc1/n1)  •  ■  ■  exp(2‘irijmkm/nm) 

the  inverse  discrete  multivariate  Fourier  transform.  The  sums  E*-  are  for  all  K  = 
(fci,  . .. ,km )  where  kv  =  0, 1,  . . .  ,n„  —  1  [y  —  1,  The  following  subroutines  are 

available  for  computing  these  transforms. 

CALL  M F F T (C,  N,m,£,  IERR) 

CALL  MFFT1(A,  B-,  N, m, £, IERR) 

Let  cj  =  aj  +  ibj  be  the  data  to  be  transformed  where  J  =  (j\,  ...  ,jm)  for  jv  = 
0, 1,  ...,n„  —  1  (u  =  1,  ...,m).  If  MFET  is  called  then  C  is  a  1-dimensional  complex 

array  containing  the  values  cj  where  cj  =  C(1  +yi  +  j2«i  +i3ni»2  + - b  *  •  •  nm-i)- 

Otherwise,  if  MFFT1  is  called  then  A  and  B  are  1-dimensional  real  arrays  containing  the 
data  aj  and  bj  respectively. 

Note.  If  MFFT  is  used  and  m  =  2  or  3,  then  instead  of  having  to  store  the  m-dimensional 
data  cj  into  a  1-dimensional  array  C,  the  data  may  be  stored  in  C  where  C  is  defined  to 
be  an  m-dimensional  array.  If  m  =  2  then  C  may  be  declared  to  be  of  dimension  ni  x  «2, 
in  which  case  C(ji  +  1, j'2  +  1)  =  cj  for  all  J  =  (ii,  J2)-  Similarly,  if  m  =  3  then  C  may  be 
declared  to  be  of  dimension  Hi  x  n2  x  n3,  in  which  case  C{j\  +  l,j2  + 1,  js  + 1)  =  cj  for  all 
J  =  Similar  comments  hold  for  A  and  B  if  MFFT  1  is  employed. 

N  is  an  array  containing  the  integers  »i,  . . . ,  nm.  The  argument  l  may  have  the  values 
1  and  -1,  and  IERR  is  a  variable.  When  MFFT  or  MFFT1  is  called,  if  there  are  no  input 
errors  then  IERR  is  set  to  0  and  the  transform 

Cj  =  Y,k  CK-exp(2x£tj1fc1/n1)  •  •  ■  exp(2xf»jm  /  rim) 

is  computed.  The  results  cj  =  aj  +  ibj  replace  the  original  data  c/  =  aj  +  ibj  in  C  (or  A 
and  B). 

1  Throughout  this  section  i  =  \/— T  and  8  —  ($l ,  denotes  an  arbitrary  point. 
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Restrictions  on  the  arguments  ni,  ...  ,nm.  When  MFFT  and  MFFT1  are  called,  each  n„ 
is  factored  by  the  routine  into  its  prime  f etc  tors.  It  is  assumed  that  the  largest  prime  factor 
of  is  <  23.  If  nv  =  n1nv  where  n„  is  the  square  free  portion  of  n„,  then  it  is  further 
assumed  that  n„  <  210  whenever  n„  is  a  product  of  two  or  more  primes. 

Error  Return.  If  an  input  error  is  detected  then  IERR  is  set  as  follows: 

IERR  =  1  if  some  n„  <  1. 

IERR  =  2  if  some  n„  has  too  many  factors. 

IERR  =  3  if  some  n„  has  a  prime  factor  greater  than  23  or  the  square  free 
portion  of  some  nv  is  greater  than  210. 

IERR  =  4  if  £  ^  ±1. 

IERR  =  5  if  m  <  0. 

The  setting  IERR  =  2  can  occur  only  when  some  n„  >  4251528. 

Remark.  The  complex  array  C  of  dimension  «i  •  •  •  nm  is  interpreted  by  MFFT  as  a  real 
array  of  dimension  2ni  •  •  ■  nm.  If  this  association  is  not  permitted  by  the  FORTRAN  being 
employed  then  use  MFFT1. 

Programming.  MFFT  and  MFFT1  are  interface  routines  for  the  subroutine  SFFT,  which 
was  written  by  Richard  C.  Singleton  (Stanford  Research  Institute). 

Reference.  Singleton,  R.  C.,  “An  Algorithm  for  Computing  the  Mixed  Radix  Fast  Fourier 
Transform,”  IEEE  Trans.  Audio  and  Electroacoustics,  vol.  AU-17  (1969),  pp  93-103. 
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DISCRETE  COSINE  AND  SINE  TRANSFORMS 

Let  n  be  a  positive  integer  and  9V  =  (u  +  1/2)tt  jn  for  v  =  0, 1,  . . . ,  n  —  1.  For  any 

n-l 

real  valued  functions  /  and  g  defined  on  the  points  9V  let  (f,g)  =  ^  /(0„)  g(9v).  Then 

v— 0 

(f,g)  is  an  inner  product  when  /  and  g  are  regarded  as  functions  defined  only  on  9„. 
Also  cos  j9  (j  =  0, 1,  ...  ,n  —  1)  form  an  orthogonal  set  of  functions  where  cos  j9  has 
norm  yfn  when  j  =  0  and  norm  \fnj 2  when  j  >  1.  Thus,  if  /  is  a  function  that  is 

n— 1 

approximated  by  /(<?)  =  a0  +  2  ^  ay  cos  j 9  then  each  ay  =  ^(/(f?),cos  j9).  The  map- 

3  =  1 

ping  /(0„)  t-»  ay  is  called  the  discrete  cosine  transform  and  its  inverse  ay  f(9v)  the 
inverse  discrete  cosine  transform. 

Alternatively,  the  functions  sin  jO  for  j  =  1,  . . . ,  n  also  form  an  orthogonal  set  where 
sin  j9  has  norm  \Jn/2  when  j  <  n  and  norm  y/n  when  j  =  n.  Thus,  if  /  is  a  function  that 

n— 1 

is  approximated  by  f{9)  =  2  Yh  by  sin  j9  +  bn  sin  n9  then  each  by  =  £(f(9),  sin  j9).  The 

3  =  1 

mapping  f[9v)  by  is  called  the  discrete  sine  transform  and  its  inverse  by  t-*  f{9v)  the 
inverse  discrete  sine  transform. 

The  subroutines  COSQB  and  COSQF  are  available  for  computing  the  discrete  cosine 
transform  and  its  inverse,  and  the  subroutines  SINQB  and  SINQF  are  available  for  comput¬ 
ing  the  discrete  sine  transform  and  its  inverse.  The  subroutine  COSQI  provides  information 
that  is  needed  for  the  cosine  and  sine  transform  routines. 

CALL  COSQI(n,  WK) 

WK  is  an  array  of  dimension  3 n  +  15  or  larger  that  is  a  work  space  for  the  routines 
COSQB,  COSQF,  SINQB,  and  SINQF.  COSQI  stores  in  WK  information  needed  for  the 
fast  Fourier  computation  of  the  discrete  cosine  and  sine  transforms  and  their  inverses.  A 
preliminary  call  must  be  made  to  COSQI  before  COSQB,  COSQF,  SINQB,  and  SINQF  can 
be  used.  After  this  preliminary  call,  COSQI  need  only  be  recalled  when  n  is  modified. 

Programming.  COSQI  employs  the  subroutines  RFFTI  and  RFFTI1.  These  routines  were 
written  by  Paul  N.  Swarztrauber  (National  Center  for  Atmospheric  Research,  Boulder, 
Colorado). 

CALL  COSQB(n,X,WK) 

X  is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contains  the 
data  f{9a),f(91),  . . . ,  / When  COSQB  is  called,  4 nay  is  computed  and  stored  in 
X(j  +  1)  for  j  =  0, 1,  . . . ,  n  -  1. 

WK  is  an  array  of  dimension  3n  +  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  must  be  set  up  by  the  routine  COSQI  before  COSQB  can  be  used. 
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Programming.  GOSQB  employs  the  subroutines  COSB1,  RFFTB,  RFFTB1,  RADB2, 
RADB3,  RADB4,  RADB5,  and  RADBG.  These  routines  were  written  by  Paul  N.  Swarz- 
trauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 

CALL  COSQF(n,X,WK) 

X  is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contains  the 
data  do, oi,  ... ,an_i.  When  COSQF  is  called,  f(9„)  is  computed  and  stored  in  X(i/  +  1) 
for  v  =  0, 1,  . . . ,  n  —  1. 

WK  is  an  array  of  dimension  3n  +  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  must  be  set  up  by  the  routine  COSQI  before  COSQF  can  be  used. 

Example.  Assume  that  X  contains  the  data  /(0o)>  •  •  •  , /(0n-i)-  When  the  statements 
CALL  COSQI(n,WK) 

CALL  COSQB(n,  Jl,WK) 

CALL  COSQF(n,X,WK) 

are  called,  COSQB  stores  4nao,  . . .  ,4nan_i  in  X  and  COSQF  then  sets  X{y+\)  =  4n/(0„) 
for  v  =  0,1,  . . . ,  n  —  1.  Thus,  the  terms  of  the  original  sequence  X  are  multiplied  by  4n. 

Programming.  COSQF  employs  the  subroutines  COSQF  1,  RFFTF,  RFFTF1,  RADF2, 
RADF3,  RADF4,  RADF5,  and  RADFG.  These  routines  were  written  by  Paul  N.  Swarz- 
trauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 

CALL  SINQB(n,A,WK) 

X  is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contains  the 
data  f{60),  ...  ,/(0„_i).  When  SINQB  is  called,  4 nbj  is  computed  and  stored  in  X(j)  for 
j  =  l,  ...  ,n. 

WK  is  an  array  of  dimension  3n  +  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  must  be  set  up  by  the  routine  COSQI  before  SINQB  can  be  used. 

Programming.  SINQB  calls  the  subroutine  COSQB.  SINQB  was  written  by  Paul  N. 
Swarztrauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 

CALL  SINQF(n,X,WK) 

X  is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contains  the 

data  bi, ... ,bn.  When  SINQF  is  called,  /(0„)  is  computed  and  stored  in  X(v  +  1)  for 

v  =  0, 1,  . . . ,  n  —  1. 

WK  is  an  array  of  dimension  3n  +  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  must  be  set  up  by  the  routine  COSQI  before  SINQF  cam  be  used. 

Example.  Assume  that  X  contains  the  data  6i,. ..  ,bn.  When  the  statements 
CALL  COSQI(n,WK) 

CALL  SINQF(n,  X,WK) 

CALL  SINQB(n,X,WK) 
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are  called,  SINQF  stores  ,/(£„_ 1)  in  X  and  SINQB  then  sets  X(j)  =  4 nbj  for 

j  =  1, . . .  ,  n.  Thus,  the  terms  of  the  original  sequence  X  are  multiplied  by  4n. 

Programming.  SINQF  calls  the  subroutine  COSQF.  The  routine  SINQF  was  written  by 
Paul  N.  Swarztrauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 
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RATIONAL  MINIMAX  APPROXIMATION  OF  FUNCTIONS 


Let  a  <  b  and  g{x)  be  a  continuous  nonvanishing  function  on  the  interval  [a,  6],  For  any 
continuous  function  f(x),  let  ||/||  denote  the  weighted  norm  maz{|/(z)[/|g(x)|  :  a  <  x  <  6}. 
Also  let  <f>{x)  be  a  continuous  strictly  monotonic  mapping  on  [a,  6].  Then  for  any  nonnegative 
integers  £  and  m,  the  subroutine  GHEBY  is  available  for  finding  a  rational  function 

_  Po  +  Pi<t>(x)  H - \-pt4>(x)1 

?o  +  ?i 4>{x)  d - b 

which  minimizes  j|i?  —  /||.  The  subroutine  performs  the  calculations  in  double  precision.  It 
is  assumed  that  the  error  curve  $(z)  =  (R{x)  -  f(x))/g(x)  satisfies  |£(z,)|  =  \\R  -  f\\  at 
precisely  £  +  m  +  2  critical  points  z0  <  ®i  <  •  •  •  <  z„(n  =  £  +  m  +  1),  and  that  6(x,+1)  = 
— 5(x,)  for  each  i  <  n. 

CALL  CH EB Y(o,  b,  F,  G,  PHI,  e,  ITER,MXITER,  £,  m,  P,  Q, 

ERROR, IERR,  WK) 

The  arguments  a  and  b  are  double  precision  real  numbers.  F,  G,  and  PHI  are  functions 
whose  arguments  and  values  are  double  precision  real  numbers.  The  functions  must  be 
declared  in  the  calling  program  to  be  of  types  DOUBLE  PRECISION  and  EXTERNAL. 
The  functions  evaluate  f{x)’,g{x),  and  <f>(x)  respectively. 

The  argument  e  is  a  double  precision  tolerance  that  is  supplied  by  the  user.  If  A  denotes 
the  estimated  value  of  ||f?— /||,  then  the  routine  converges  when  the  error  curve  S(x)  satisfies 
A(1  —  e)  <  |£(zi)|  <  A(1  +  e)  for  each  x,'.  Thus  e  specifies  the  relative  agreement  that  must 
be  attained  between  \\f  -  £||  and  the  |5(a:*)|.  Normally  the  setting  e  =  10-4  will  give 
satisfactory  results.  It  is  required  that  0  <  e  <  10“ 2 . 

The  Remes-type  algorithm  designed  by  Cody,  Fraser,  and  Hart  is  employed.  This  algo¬ 
rithm  normally  requires  less  than  20  iterations.  The  argument  MXITER  =  the  maximum 
number  of  iterations  that  may  be  performed.  This  argument  is  set  by  the  user.  The  related 
argument  ITER  is  an  integer  variable  that  is  set  by  the  routine.  When  CHEBY  terminates, 
ITER  will  have  for  its  value  the  number  of  iterations  that  were  actually  performed. 

P  is  a  double  precision  array  of  dimension  £+1,  Q  a  double  precision  array  of  dimension 
m  +  1,  ERROR  a  double  precision  variable,  and  IERR  an  integer  variable.  When  CHEBY 
terminates,  if  the  rational  function  approximation  i?(x)  has  been  obtained  then  IERR  is 
assigned  the  value  0  and  ERROR  is  the  estimated  error  ||R  -  /||.  The  coefficient  of  the 
numerator  of  R(x)  is  stored  in  P(i  +  1)  for  *  =  0,1,...  ,£,  and  the  coefficient  gy  of  the 
denominator  is  stored  in  Q(j  +  1)  for  j  =  0, 1, . . .  ,  m.  The  coefficient  q0  will  always  have 
the  value  1. 

Let  k  =  £+m  +  2.  Then  WK  is  a  double  precision  array  of  dimension  ifc(fc  +  5)  or  larger 
that  is  used  for  a  work  space. 
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Error  Return.  IERR  is  assigned  one  of  the  following  values  when  the  desired  minimizing 
rational  function  R(x)  is  not  obtained. 

IERR  =  1  An  input  error  was  detected.  Either  £  <  0,  m  <  0,  e  <  0,  e  >  10~2, 
or  g(x)  =0  for  some  point  x. 

IERR  =  2  MXITER  iterations  were  performed.  More  iterations  are  needed 
to  obtain  R(x). 

IERR  =  3  The  system  of  linear  equations  that  define  the  coefficients  pt-  and 
qj  was  found  to  be  singular.  This  indicates  that  for  the  current 
values  of  £  and  m,  the  numerator  and  denominator  of  R(x)  may 
have  common  factors. 

IERR  =  4  A  nonmonotonic  sequence  of  critical  points  n  was  obtained.  Mod¬ 
ify  £  and/or  m. 

IERR  —  5  The  value  of  the  error  curve  S  (x)  at  some  critical  point  n  appears 
to  be  too  large.  This  indicates  that  R(x)  may  have  poles,  and  that 
m  (or  possibly  a  or  b)  may  have  to  be  modified. 

IERR  =  6  CHEBY  completely  failed  to  find  (or  roughly  approximate)  R(x). 

All  information  in  P,Q,  and  ERROR  should  be  ignored. 

If  IERR  =.  2,3,4,  or  5  then  P  and  Q  contain  the  coefficients  of  the  most  recent  rational 
function  approximation  i?(x)  obtained,  and  ERROR  is  an  estimate  of  the  error  ||ii  —  /||  of 
the  approximation. 

Remark.  The  two  most  common  weighting  functions  employed  are  g(x )  =  1  and  j(z)  = 
f  (x).  If  g(x)  =  1  then  the  absolute  error  is  minimized  in  constructing  R{x).  If  g(x)  =  f(x) 
then  the  relative  error  is  minimized. 

Programming.  CHEBY  employs  the  subroutines  CHEBY1,  CERR,  and  DPSLV.  These 
routines  were  written  by  A.  H.  Morris.  CHEBY,  CHEBY1,  and  CERR  are  slightly  modified 
translations  of  the  ALGOL  60  procedures  Chebychev,  lineq,  del,  and  surmis  given  in  the 
reference. 

Reference.  Cody,  W.  J.,  Fraser,  W.,  and  Hart,  J.  F., “Rational  Chebychev  Approximation 
using  Linear  Equations,”  Numerische  Mathematik  12  (1968),  pp.  242-251. 
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Lp  APPROXIMATION  OF  FUNCTIONS 


For  any  continuous  real-valued  function  f(x)  defined  on  the  interval  [a, 6],  let  ||/|[p 
denote  the  Lp  norm  defined  by 

ll/ll,  =  (/.*  l/WI'-fa)1''  if  0  <  p  <  GO 

11/11,.=  max{|/(a:)|  :  a  <  x  <  t}  if  p=oo. 

If  p  —  oo  then  the  norm  is  also  known  as  the  Chebyshev  norm.  For  any  continuous  function 
/,  0  <  p  <  oo,  and  e  >  0,  the  subroutine  ADAPT  is  available  for  finding  a  continuous 
piecewise  polynomial  function  <j>  that  satisfies  ||/  -  <£j|p  <  e. 

CALL  ADAPT  (F,  a,b,e,k,  ERROR,XKNOTS,  C,  IND,  p,  n,  i,  ANORM, 

DX,MO  ,m,XBRE  AK  ,KDIFF  ,DLEFT,DRIGHT) 

It  is  assumed  that  the  polynomials  which  form  the  approximation  4>  are  of  degree  <  n. 
The  argument  n  must  satisfy  1  <  n  <  19,  and  IND  is  a  variable.  When  ADAPT  is  called,  if 

there  are  no  input  errors  and  <f>  is  successfully  constructed,  then  IND  is  set  to  0,  a  sequence 

of  points  o  =  xi  <  •••  <  ifc_i  <  Xfc  =  b  is  selected,  and  <j>  takes  the  form 

4>(x)  =  Ci0  +  Cil  (x  -  Xi)  -i - 1-  Cin(x  -  Xi)n  X,  <  X  <  Xi+1 

for  :  =  1,  . . . ,  k  —  1.  The  points  Xi,  . . .  ,xk  are  called  the  knots  (or  nodes)  of  <f>. 

The  argument  p  is  the  maximum  number  of  polynomials  that  may  be  used  in  forming 
<f>.  ERROR  and  k  are  variables,  XKNOTS  an  array  of  dimension  p  +  1  or  larger,  and  C  a 
2-dimensional  array  of  dimension  p  x  (n  +  1).  ADAPT  sets  k  to  the  number  of  knots  that 
are  generated.  The  knots  z1}  ...  ,xk  are  stored  in  the  XKNOTS  array,  and  the  coefficients 
CiO  j  •  •  *  j  Ctn  are  stored  in  C(i,  1),  . . . ,C(»‘,n  +  1)  for  i  =  1,  . .  -  1.  ERROR  is  a  rough 

estimate  of  the  error  ||/  —  <j>\\p. 

The  argument  l  specifies  the  degree  of  smoothness  that  the  approximation  <f>  must 
satisfy.  It  is  assumed  that  0  <  t  <  10  and  n  >  22.  If  t  =  0  then  it  is  only  required  that 
<f>  be  continuous  on  the  interval  [a,  b].  Otherwise,  if  i  >  1  then  it  is  assumed  that  /  is  of 
class  C*'  on  [a,  6]  except  at  possibly  a  finite  number  of  points  (called  break  points),  and  it 
is  required  that  <j>  be  of  class  Cl  on  [a,  6]  except  possibly  at  the  break  points. 

The  argument  m  specifies  the  number  of  break  points  of  /.  It  is  assumed  that  m  <  20. 
If  m  =  0  then  the  arguments  XBREAK,KDIFF,DLEFT,  and  DRIGHT  can  be  ignored. 
Otherwise,  if  m  >  1  then  it  is  assumed  that  XBREAK,KDIFF,DLEFT,  and  DRIGHT  are 
arrays  of  dimension  m  or  larger,  and  that 

XBREAK(t)  =  the  ttk  break  point,  call  it  u,-, 

KDIFF(t)  =  the  smallest  integer  Vi  for  which  the  v\h  derivative  of  /  does 
not  exist  or  is  not  continuous  at  u», 

DLEFT(t)  =  the  value  from  the  left  of  the  v\h  derivative  at  u*,  and 

DRIGHT(t)  =  the  value  from  the  right  of  the  v\h  derivative  at  u» 
for  i  =  1,  . . . , m.  It  is  also  assumed  that  a  <«!<•■•<  um  <  6  and  n  >  2i \  for  each  i/,-. 
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F  is  the  name  of  a  user  defined  function  that  has  the  value  F(x,  D)  =  /  (x)  for  a  <  x  <  b. 
If  £  =  0  then  D  can  be  ignored.  (However,  D  must  still  be  given  as  an  argument  of  F.) 
Otherwise,  if  £  >  1  then  D  is  an  array  of  dimension  greater  than  or  equal  to  £.  For  any  x 
not  a  break  point  in  XBREAK,  the  user  must  set  D(j)  =  the  jth  derivative  of  /  at  x  for 
j  <  £.  However,  if  x  =  XBREAK  (t)  then  the  user  need  only  set  D(j)  =  the  jih  derivative 
of  /  at  x  for  j  <  KDIFF(t).  The  function  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

The  argument  DX  specifies  the  maximum  distance  to  be  permitted  between  the  knots 
Xi,  and  the  argument  ANORM  specifies  the  norm  to  be  used.  Set 

ANORM  =  ±1.0  for  Li  approximation. 

ANORM  =  ±2.0  for  L2  (least  squares)  approximation. 

ANORM  =  3.0  for  L0 0  (minimax)  approximation. 

ANORM  =  —  pfor  Lp  (0  <  p  <  oo)  approximation. 

Before  considering  the  argument  MO,  one  should  be  briefly  acquainted  with  how 
ADAPT  operates.  ADAPT  employs  the  following  procedure  to  construct  <j>. 

(1)  Set  I  =  [a,i]  and  k  =  1.  Let  o  be  the  first  knot  of  <j>. 

(2)  If  the  interior  of  I  contains  no  break  points  then  go  to  (3).  Otherwise,  if  /  =  [c,  d]  then 
partition  I  into  the  subintervals  [c,u]  and  [ti,  d]  where  u  is  the  smallest  break  point 
greater  than  c.  Stack  the  right  subinterval  [u,  d\  and  reset  I  to  [c,u]. 

(3)  Construct  a  polynomial  <f>j  on  I  using  Hermite  interpolation.  If  the  length  of  the  interval 
/  is  <  DX  and  <j>i  satisfactorily  approximates  /  on  /,  then  go  to  (4).  Otherwise  go  to 

(5)- 

(4)  Set  k  to  be  k  +  1.  Let  <j>j  be  the  ( k  -  l)at  polynomial  forming  <f>  and  let  the  right  end 
point  of  I  be  the  kth  knot  of  <f>.  If  the  interval  stack  is  empty  then  the  procedure  is 
finished.  Otherwise,  obtain  from  the  stack  the  next  interval  I  to  be  considered  and 
return  to  (2). 

(5)  The  polynomial  <f>i  cannot  be  used.  Partition  I  into  halves,  stack  the  right  subinterval 
and  reset  I  to  be  the  left  subinterval.  Then  go  to  (3). 

The  argument  MO  specifies  the  accuracy  criterion  that  the  approximation  <j>  is  to  satisfy 
on  a  subinterval  I  —  [c,  d]  of  [a,  b ].  It  is  assumed  that  MO  =  0, 1, 2.  If  the  Loo  norm  is  used 
then  MO  is  ignored1  and  <j>  is  required  to  satisfy  |/(x)  —  <^(x)|  <  e  for  c  <  x  <  d.  Otherwise, 
if  the  Lp  (0  <  p  <  oo)  norm  is  used  then  <j>  is  required  to  satisfy: 

f  |/(x)  —  ^(z)|p  dx  <  y — -  ep  for  MO  =  0 

Je  ~  b  -  a 

|/(x)  —  <f>(x)  |p  dx  <  ep  for  MO  =  2 

The  setting  MO  =  0,  which  is  the  most  commonly  used  setting,  requires  the  total  error 
11/  —  ^1  Ip  ^  e-  The  alternate  setting  MO  =  2  employs  e  to  control  local  accuracy.  If  (j> 
consists  of  k  —  1  polynomials  then  the  total  error  ||/  —  <f> ||p  <  (k  —  l)1/,pe.  This  setting  can 

however,  it  is  still  required  that  MO  =  0,1,2. 
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be  useful  when  /  is  rough.  A  (heuristic)  compromise  strategy  is  provided  when  MO  =  1. 
At  each  step  in  the  formation  of  <f>,  the  MO  =  1  strategy  estimates  the  total  number  of 
subintervals  that  will  finally  be  needed  and  adjusts  the  error  requirement  for  the  subinterval 
I  accordingly.  This  strategy  attempts  to  keep  the  total  error  to  a  minimum  while  relaxing 
the  local  accuracy  criterion  demanded  by  the  MO  =  0  setting. 

Remarks.  IND,  k,  p,  n,  £,  MO,  m,  and  KDIFF  are  integer  arguments.  All  other  arguments 
(including  F )  are  double  precision  arguments. 


Error  Return.  ADAPT  assigns  IND  one  of  the  following  values: 


IND  = 
IND  = 

IND  = 
IND  = 


IND  = 

IND  = 
IND  = 

IND  = 

IND  = 

IND  = 


0  The  approximation  was  successfully  constructed. 

-1  Either  a  >  b  or  one  of  the  arguments  e,  n,  £,  ANORM,  MO,  m  is 
assigned  an  incorrect  value. 

—2  [a,  b]  is  too  small  an  interval. 

—3  DX  is  less  than  (6  —  a)/p.  Since  only  p  subintervals  can  be  used 
and  each  sjibinterval  must  be  of  length  <  DX,  the  interval  [a,  i] 
cannot  be  covered.  Make  DX  or  p  larger. 

—4  The  restriction  a  <  uj  <  •••  <  um  <  6  on  the  break  points  is 
violated. 

—5  Either  KDIFF(i)  <  0  or  KDIFF(i)  >  (n  —  l)/2  for  some  i. 

1  ADAPT  selected  p  +  1  knots.  More  knots  are  needed  to  complete 
the  problem. 

2  A  subinterval  I  =  [c,  dj  must  be  partitioned  into  subintervals  [c,  ti] 
and  [u,  d]  where  u  is  a  break  point.  However,  this  cannot  be  done 
either  because  the  interval  stack  is  full,  or  partitioning  will  produce 
too  small  an  interval.  (The  stack  can  hold  only  50  subintervals). 

3  A  subinterval  must  be  partitioned  because  its  length  is  greater 
than  DX.  However,  this  cannot  be  done  since  the  interval  stack  is 
full. 

4  A  subinterval  must  be  partitioned  so  that  the  accuracy  criterion 
can  be  satisfied.  However,  this  cannot  be  done  either  because  the 
stack  is  full,  or  partitioning  will  produce  too  small  an  interval. 


If  an  input  error  is  detected  (i.e.,  if  IND  <  0)  then  no  computation  is  performed.  Otherwise, 
if  IND  >  0  then  when  ADAPT  terminates  k  =  the  number  of  knots  generated,  XKNOTS 
contains  the  knots,  C  contains  the  coefficients  of  the  polynomials  generated,  and  ERROR 
contains  the  error  estimate  for  /  —  (j>  over  the  interval  covered. 


Remarks. 

(1)  If  the  Lqo  norm  is  used  then  e  controls  absolute  accuracy,  not  relative  acuracy.  This 
should  be  kept  in  mind  when  e  is  to  be  set  for  any  Lp  norm. 

(2)  ADAPT  requires  more  time  when  l  >  2  than  when  i  =  0  or  1.  However,  the  choice  of 
the  norm  normally  has  little  effect  on  the  efficiency  of  the  routine. 

(3)  ADAPT  can  yield  excellent  results  even  when  the  derivatives  of  /  have  singularities. 
The  one  major  exception  is  when  the  first  derivative  of  /  is  not  bounded.  Then  the 
routine  can  be  expected  to  fail. 
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Example.  The  following  code  can  be  used  for  approximating  f(x )  =  ex  on  the  interval  [0, 1], 

DOUBLE  PRECISION  F,  A,  B,  EPS,  ERROR,  ANORM,  DX 
DOUBLE  PRECISION  XKNOTS  (11),  C(10,20) 

INTEGER  KDIFF(l) 

DOUBLE  PRECISION  XBREAK(1),DLEFT(1),DRIGHT(1) 

EXTERNAL  F 

DATA  MAX,  A,  B,  DX/10,  0.D0,  1.D0,  1.D0/ 

N  =  8 
L  =  1 

EPS  =  l.D-12 
ANORM  =  3. DO 

CALL  ADAPT(F, A, B, EPS, K, ERROR, XKNOTS, C,IND, 

*  MAX, N,L, ANORM, DX,0,0,XBREAK,KDIFF,DLEFT,DRIGHT) 

Here  F  may  be  defined  by: 

DOUBLE  PRECISION  FUNCTION  F(X,D) 

DOUBLE  PRECISION  X,D(1) 

F  =  DEXP(X) 

D(1)  =  F 

RETURN 

END 

In  the  ADAPT  statement  XBREAK,  KDIFF,-  DLEFT,  and  DRIGHT  are  ignored  since 

m  =  0. 

Programming.  ADAPT  employs  the  subroutines  ADAPTl,  ADSET,  ADTAKE,  ADCOMP, 
NEWTON,  ADCHK,  ADPUT,  ADTRAN  and  functions  ERRINT,  POLYDD.  These  rou¬ 
tines  exchange  information  in  labeled  common  blocks.  The  block  names  are  INPUTZ, 
RESULZ,  KONTRL,  and  COMDIF.  The  routines  were  written  by  John  R.  Rice  (Purdue 
University)  and  modified  by  A.  H.  Morris.  The  function  DPMPAR  is  also  used. 

References. 

(1)  Rice,  J.  R.,  “Algorithm  525.  ADAPT,  Adaptive  Smooth  Curve  Fitting,”  ACM  Trans. 
Math  Software  4  (1978),  pp.  82-94. 

(2)  _ _,  “Adaptive  Approximation,”  J.  Approx.  Theory  16  (1976),  pp.  329-337. 
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CALCULATION  OF  THE  TAYLOR  SERIES  OF 
A  COMPLEX  ANALYTIC  FUNCTION 

Let  f{z )  =  an(z  —  z0)n  denote  the  Taylor  series  of  an  analytic  function  /  around 

n>0 

a  point  zq.  Then  the  subroutines  CPSC  and  DCPSC  are  available  for  obtaining  the  coef¬ 
ficients  an  of  the  series.  CPSC  obtains  single  precision  results  and  DCPSC  obtains  double 
precision  results. 

CALL  C  P  S  C  (/,  z0 , n,IND  ,e, R,  A, ERR) 

It  is  assumed  that  f(z )  is  a  user  defined  function  whose  arguments  and  values  are 
complex  numbers.  The  argument  /  must  be  declared  in  the  calling  program  to  be  of  types 
COMPLEX  and  EXTERNAL. 

The  argument  zq  is  complex,  n  is  an  integer  where  1  <  n  <  51,  and  A  is  a  complex 
array  of  dimension  n  or  larger.  IND  may  be  any  integer.  If  IND  =  0  then  ay  is  computed 
and  stored  in  A(j  +  1)  for  j  =  0, 1,  . . . ,  n  —  1.  Otherwise,  if  IND  #  0  then  f{zo)  and  the 
derivatives  /'( zq ),  .  ■  • ,  are  computed  and  stored  in  A. 

The  argument  e  specifies  the  relative  accuracy  of  /.  If  it  is  estimated  that  /  produces 
results  accurate  to  k  significant  decimal  digits  then  one  may  set  e  =  10-fc.  It  is  assumed 
that  e  >  0.  If  e  =  0  then  the  results  of  /  are  assumed  to  be  correct  to  machine  precision. 

When  CPSC  is  called,  f(z)  is  evaluated  on  circles  of  various  radii  around  the  point 
zq.  R  is  a  real  variable.  On  input,  R  is  the  radius  of  the  first  circle  on  which  f(z)  is  to  be 
evaluated.  After  using  this  radius,  the  radius  is  repeatedly  modified  (first  by  factors  of  2 
or  1/2)  until  a  suitable  final  radius  rc  is  obtained  for  deriving  the  values  of  the  coefficients 
ay.  This  radius,  whose  value  depends  on  e,  is  called  the  computational  radius  of  the  series 
Eay(z  —  zo)3.  When  the  routine  terminates,  R  is  assigned  the  value  re. 

ERR  is  a  real  array  of  dimension  n  or  larger.  On  output,  ERR(j)  is  the  estimated 
absolute  error  of  A(j)  for  j  =  1,  . . . ,  n. 

Usage.  Given  a  radius  R,  f(z)  is  evaluated  on  k  equidistant  points  on  the  circle  of 
radius  R  around  zq  where 

k  =  8  when  1  <  n  <  6, 
k  =  16  when  7  <  n  <  12, 
k  —  32  when  13  <  n  <  25, 
k  =  64  when  26  <  n  <  51. 

It  is  assumed  that  f(z)  has  at  least  one  nonzero  coefficient  ay  among  the  first  k/2  coefficients, 
and  at  least  one  nonzero  coefficient  among  the  next  k/2  coefficients.  Thus,  the  routine 
should  not  be  used  to  obtain  coefficients  of  a  low  degree  polynominal  such  as  f(z)  =  1  -  z2. 
In  such  cases,  the  results  will  normally  be  incorrect. 

In  general,  the  selection  of  the  radius  R  of  the  first  circle  on  which  f(z)  is  evaluated  is 
not  bothersome.  A  randomly  selected  value  of  moderate  size,  such  as  R  =  6.2738,  almost 
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always  suffices.  No  difficulties  normally  arise  when  the  initial  radius  R  is  greater  than  the 
radius  of  convergence  of  the  series  S a3(z  —  zo)J-  However,  difficulties  do  arise  when 

(1)  the  routine  attempts  to  evaluate  /  too  close  to  (or  exactly  at)  a  singularity, 

(2)  /  has  a  Taylor  series  expansion  which  contains  one  or  more  extremely  large  isolated 
terms  (e.g.,  f(z )  =  108  +  sinz), 

(3)  /  has  a  branch  point  near  2r0,  or 

(4)  The  initial  radius  R  is  too  far  from  the  computational  radius  rc  (see  the  error  return 
section  below) . 

The  risk  of  (1)  occurring  is  minimized  by  the  random  selection  of  an  initial  radius  R.  For 
(2)  and  (3),  a  severe  loss  of  accuracy  can  occur  when  a  large  number  of  coefficients  are 
requested.  In  these  cases,  any  loss  of  accuracy  is  reported  by  the  ERR  array. 

Error  return.  A(j)  is  assigned  the  value  0  and  ERR(y)  is  set  to  1010  for  j  =  1,  . . .  ,n  when 
the  initial  radius  R  differs  from  rc  by  a  factor  of  30000  or  greater. 

Programming.  CPSC  was  written  by  Bengt  Fornberg  (California  Institute  of  Technology) 
and  modified  by  A.H.  Morris.  CPSC  employs  the  function  SPMPAR. 

References. 

(1)  Fornberg,  B.,  “Numerical  Differentiation  of  Analytic  Functions,”  ACM  Trans.  Math 
Software  7,  1981,  pp.  512-526. 

(2)  _ /Algorithm  579.  CPSC:  Complex  Power  Series  Coefficients,”  ACM  Trans. 

Math  Software  7,  1981,  pp.  542-547. 

C A  L  L  D  C  P  S  C  ( F,  x0 ,  y0 ,  n ,  IND  ,e,  R , AR, AI  ,ERR) 

F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

GALL  F(z,y,u,v) 

This  subroutine  is  used  for  evaluating  f(z)  at  point  z.  The  arguments  x  and  y  are  the 
real  and  imaginary  parts  of  z,  and  u  and  v  are  the  real  and  imaginary  parts  of  /(*).  The 
arguments  z  and  y  have  double  precision  values,  and  u  and  v  are  double  precision  variables. 
F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  arguments  x0  and  yo,  which  have  double  precision  values,  are  the  real  and  imagi¬ 
nary  parts  of  zq.  The  argument  n  is  an  integer  where  1  <  n  <  51,  and  AR  and  AI  are  double 
precision  arrays  of  dimension  n  or  larger.  IND  may  be  any  integer.  If  INl)  =  0  then  the' 
real  and  imaginary  parts  of  ay  are  stored  in  AR(j  +  1)  and  Al(j  +  1)  for  j  =  0,1,  . . . ,  n  —  1. 
Otherwise,  if  IND  ^  0  then  the  real  and  imaginary  parts  of  /(z0)  and  the  derivatives 
f'(zo),  . . . ,  /(n-1)(z0)  are  stored  in  AR  and  AI  respectively. 

The  argument  e,  which  has  double  precision  values,  specifies  the  relative  accuracy  of 
the  subroutine  F.  If  it  is  estimated  that  F  produces  results  accurate  to  k  decimal  digits 
then  one  may  set  e  =  10-fc.  It  is  assumed  that  e  >  0.  If  e  =  0  then  the  results  of  F  are 
assumed  to  be  correct  to  machine  precision. 

When  DCPSC  is  called,  /(z)  is  evaluated  on  circles  of  various  radii  around  the  point 
zq.  R  is  &  double  precision  variable.  On  input,  R  is  the  radius  of  the  first  circle  on  which 
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/(z)  is  to  be  evaluated.  After  using  this  radius,  the  radius  is  repeatedly  modified  (first  by 
factors  of  2  or  1/2)  until  a  suitable  final  radius  rc  is  obtained  for  deriving  the  values  of  the 
coefficients  ay.  This  radius,  whose  value  depends  on  e,  is  called  the  computational  radius 
of  the  series  Say (2  —  z0): .  When  the  routine  terminates  R  is  assigned  the  value  rc. 

ERR  is  a  double  precision  array  of  dimension  n  or  larger.  On  output,  ERR(y)  is  the 
estimated  absolute  error  of  the  complex  value  stored  in  AR(y)  and  AI(y)  for  j  =  1,  . . . ,  n. 

Usage.  DCPSC  is  used  in  the  same  manner  as  CPSC.  See  the  usage  section  for  CPSC. 

Error  return.  AR(j')  and  AI(j')  are  assigned  the  value  0  and  ERR(j)  is  set  to  1010  for 
j  =  1,  . . . ,  n  when  the  initial  radius  R  differs  from  rc  by  a  factor  of  30000  or  greater. 

Programming.  DCPSC  is  an  adaptation  by  A.H.  Morris  of  the  subroutine  CPSC,  written 
by  Bengt  Fornberg  (California  Institute  of  Technology).  DCPSC  employs  the  function 
DPMPAR. 

References. 

(1)  Fornberg,  B., “Numerical  Differentiation  of  Analytic  Functions,”  ACM  Trans.  Math 
Software  7,  1981,  pp.  512-526. 

(2)  _ ,  “Algorithm  579.  CPSC:  Complex  Power  Series  Coefficients,”  ACM  Trans. 

Math  Software  7,  1981,  pp.  542-547. 
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LINEAR  INTERPOLATION 


Let  a  be  a  real  number  and  (ii,  t/i),  . . . ,  (xn,  y„)  a  sequence  of  points.  The  following 
function  performs  a  linear  interpolation  at  point  a. 

TRP  (a,n,X,Y) 

It  is  assumed  that  n  >  2  and  Xi  <  <  xn.  X  and  Y  are  arrays  containing  the 

abscissas  x\,  ...  ,xn  and  ordinates  yi,  .  ..,yn  respectively.  TRP(a, n,X,Y)  =  b  where  b  is 
the  value  of  the  interpolation  at  a. 

Programmer.  A.  H.  Morris 
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LAGRANGE  INTERPOLATION 


Let  {(xi,  y.)  :  t  =  1,  . ...  ,n}  be  a  set  of  n  >  2  points  where  x\  <  •••  <  xn,m  be  an 
integer  where  2  <  m  <  n,  and  ®i,  ...,**  be  k  >  1  points  at  which  m  point  Lagrange 
interpolation  is  to  be  performed.  The  subroutine  LTRP  is  available  for  performing  this 
interpolation. 

CALL  LTRP(m,  X,  Y,  n,  XI, YI,  k,  T,  IERR) 

X  is  an  array  containing  x\,  ...,xn,  Y  an  array  containing  yi,  .  ..,y„,  XI  an  array 
containing  x\,  . .  .  ,Xfc,  and  YI  an  array  of  dimension  k  or  larger.  When  LTRP  is  called,  if 
no  input  errors  are  detected  then  interpolation  is  performed  at  each  xy  and  the  result  stored 
in  YI(j)  for  j  =  1, . . . ,  k. 

T  is  an  array  of  dimension  m  or  larger.  The  array  is  used  as  a  temporary  storage  area 
by  the  routine. 

Error  Return.  IERR  is  a  variable  that  is  set  by  the  routine.  If  no  input  errors  are  detected 
then  IERR  is  assigned  the  value  0.  Otherwise,  IERR  is  assigned  one  of  the  following  values: 
IERR  =  1  if  m  <  2. 

IERR  =  2  if  m  >  n. 

IERR  =  3  if  k  <  1. 

When  an  error  is  detected  LTRP  immediately  terminates. 

Algorithm.  If  xy  =  (x ,•  +  xi+m)/2  for  some  i,  then  (zt-,  y»),  . . . ,  (xt+m_i,y,+m_1)  are  the  m 
data  points  used  in  the  Lagrange  interpolation  at  ij.  Otherwise,  the  data  points  selected 
for  the  interpolation  are  those  m  points  (a:,-,  y,-)  whose  abscissas  are  closest  to  Xj. 

Linear  Interpolation.  For  m  =  2,  if  the  abscissae  x»  are  not  equally  spaced  then  LTRP 
can  produce  different  results  than  the  linear  interpolating  function  TRP.  If  Xj  lies  in  the 
interval  [ij,x,-+1)  then  TRP  always  uses  the  data  points  (x,-,yi)  and  (xi+1,yi+1)  to  find 
the  interpolated  value  at  xy.  However,  the  operation  of  LTRP  is  somewhat  different.  For 
example,  if  the  point  xy  in  [xi,Xj+1)  is  closer  to  Xi_x  than  to  xy+i,  then  (xi_1,yi_1)  and 
(z»,y»)  will  be  the  data  points  employed  in  the  interpolation.  Thus,  TRP  will  normally  be 
the  procedure  that  will  be  desired  for  linear  interpolation. 

Programming.  Developed  by  A.  H.  Morris.  The  portion  of  the  code  for  finding  the  subin¬ 
terval  containing  xy  was  written  by  Rondall  E.  Jones  (Sandia  Laboratories). 
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HERMITE  INTERPOLATION 

Let  x\ ,  ...,Xk  be  k  >  1  distinct  points.  For  each  Xi  assume  that  we  are  given  >  1 
values  y,-,yt-,  . . . ,  y,-  *  If  n  —  «!  +  •••  +  «*,  then  there  exists  a  unique  polynomial  of 
degree  n  —  I  which  satisfies 

P(xi )  =  Vi 

p'M  =  y' 


=  si!”'-1’ 

for  each  *  =  1,  The  subroutine  HTRP  is  available  for  obtaining  this  polynomial. 


CALL  HTRP(«,Jt,F,A,WK,IERR) 


X  and  Y  are  arrays  of  dimension  n  containing  the  following  information:  X(j)  = 
xi  for  j  =  1,  and  F(l),  . ..,F(ni)  contain  the  values  yx  ,y^,  For 

*  =  2,  ...,k  let  mi  =  «!  +  •••  +  n,_i.  Then  X{nn  +  j)  =  Xi  for  j  =  1,  and 

Y(mi  +  1),  ...  ,Y(mi  +  rii)  contain  the  values  yi,y^,  ... ,y|n<_1\ 

A  is  an  array  of  dimension  n  and  IERR  an  integer  variable.  When  HTRP  is  called, 
if  no  errors  are  detected  then  IERR  is  assigned  the  value  0  and  the  coefficients  a,-  of  the 

n— 1  ^  3 

polynomial  p(x)  =  a0  +  X)  aAx  ~  -^(1))  •  *  {x  —  X(j))  are  computed  and  stored  in  A(j  + 1) 

i= i 

for  j  =  0,1,  ...,n  -  1. 


WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

Error  Return.  If  an  error  is  detected  then  IERR  is  assigned  one  of  the  following  values: 
IERR  =  1  The  argument  n  is  not  positive. 

IERR  =  2  There  exists  integers  i  and  £  for  which  X(t)  =  X(£)  but  X(i) 

X(j)  for  some  j  where  »  <  j  <  l.  In  this  case,  the  values  *  and  £ 
are  stored  (in  floating  point  form)  in  WK(1)  and  WK(2). 

When  an  error  is  detected,  the  routine  immediately  terminates. 


Example.  If  p(0)  =  2,  p(-l)  =  1,  and  py(-l)  =  2  where  xx  =  0  and  x2  =  -1,  then  HTRP 
stores  2, 1,  —1  in  A.  Hence,  p(a:)  =  2  +  x  —  x(x  +  I)  is  the  desired  polynomial. 


n— 1 

Remark.  The  Newton  representation  a0  +  E  aAx -^(1))  •••(«-  X(i))  of  the  polynomial 

.  .  J=1  n— 1 

p{x)  can  be  converted  to  the  Taylor  series  representation  J2  c3{x  ~  by  the  subroutine 
PCOEFF. 


Programmer.  A.  H.  Morris 
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CONVERSION  OF  REAL  POLYNOMIALS  FROM  NEWTON 
TO  TAYLOR  SERIES  FORM 


n  — 1 

For  n  >  1  let  p(x)  =  ao  +  X)  aj(x  ~  Zi)  •••(*  —  zy).  Then  for  any  real  number  a, 

3=1 

the  subroutine  PCOEFF  is  available  for  converting  the  polynomial  p(x )  to  the  Taylor  series 

n— 1 

form  J2  ci(x  ~  a)J- 
3=0 

CALL  PCOEFF  (a,  n,X,  A,  C,T) 

X  is  a  single  precision  real  array  containing  x\,  . . . ,  xn~1}  A  a  single  precision  real  array 
containing  a0,ai,  . . . ,  an_i  where  ay  is  stored  in  A(j  +  1)  for  j  =  0, 1,  . . .  ,n  —  1,  and  C 
a  single  precision  real  array  of  dimension  n  or  larger.  When  PCOEFF  is  called  then  the 
coefficients  cy  of  the  Taylor  series  representation  are  computed  and  stored  in  C(j  +  1)  for 
j  =  0,1, 

T  is  a  double  precision  array  of  dimension  n  or  larger.  The  array  is  a  work  space  for 
the  routine.  (The  conversion  of  the  coefficients  is  done  in  double  precision.) 

Note.  A  and  C  may  reference  the  same  storage  area,  in  which  case  the  results  cy  will 
overwrite  the  input  data  ay. 

Programmer.  A.  H.  Morris 
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LEAST  SQUARES  POLYNOMIAL  FIT 


Let  {(a:,-,  y»)  :  *  =  1,  . . .  ,m}  be  a  set  of  m  >  2  points  where  x,-  x}-  for  t  j.  Then 

for  any  positive  integer  n  where  n  <  m,  the  subroutine  PFIT  is  available  for  obtaining  the 

(unique)  nth  degree  polynomial  p(x)  =  £  ayx5'  which  minimizes  (p(xt)  -  yt)2. 

3=0  t=l 

CALL  PFIT(n,  m, X ,  Y,  A, RNORM,PHI,WK,IERR) 

X  is  an  array  containing  x1}  Y  an  array  containing  yi,  and  A  an 

array  of  dimension  n  + 1  or  larger.  RNORM  and  IERR  are  variables.  When  PFIT  is  called, 
if  no  input  errors  are  detected  then  IERR  is  set  to  0,  the  coefficients  ny  of  p(x)  are  stored 
in  A{j  +  1)  for  j  =  0,1,  ...  ,n,  and  RNORM  is  assigned  the  value  ^/E,(p(xi)  -  yt)2. 

PHI  is  an  array  of  dimension  2 (n  +  1)  or  larger,  and  WK  is  an  array  of  dimension  4m 
or  larger.  PHI  and  WK  are  work  spaces  for  the  routine. 

Error  Return.  IERR  =  1  if  n  <  1  or  n  >  m. 

Algorithm.  The  abscissas  x»  are  first  mapped  into  values  in  the  interval  [-1,1].  Then  the 
Forsythe  procedure  is  used. 

Programmer.  A.  H.  Morris 
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WEIGHTED  LEAST  SQUARES  POLYNOMIAL  FIT 

Let  {(z,-,  y.)  :  t  =  1,  . . . ,  m}  be  a  set  of  m  >  2  points  where  z,  ^  x3-  for  i  ^  j,  and 
let  u>i  >  0(«  =  1,  . . .  ,m)  be  weights.  It  is  assumed  that  mw  >  2  where  mw  is  the  number 
of  nonzero  weights.  For  any  positive  integer  n  where  n  <  mW)  the  subroutine  WPFIT  is 

n 

available  for  finding  the  (unique)  nth  degree  polynomial  p(x)  =  J2  ayzJ  which  minimizes 

E  ™.-(p(z*)  -  yi)2.  J~c 

i=l 

CALL  WPFIT(n,  m,  X,  Y,  W ,  A,  RNORM,PHI,WK,IERR) 

X  is  an  array  containing  xi,  . . . ,  xm,  Y  an  array  containing  yi ,  . . . ,  ym ,  W  an  array 
containing  u/i,  . . . ,  wm,  and  A  an  array  of  dimension  n  +  1  or  larger.  RNORM  and  IERR 
are  variables.  When  WPFIT  is  called,  if  no  input  errors  are  detected  then  IERR  is  set  to 
0,  the  coefficients  ay  of  p(x)  are  computed  and  stored  in  A(j  +  1)  for  j  =  0, 1,  . . .  ,n,  and 
RNORM  is  assigned  the  value  -  yi)z. 

PHI  is  an  array  of  dimension  2(n  +  1)  or  larger,  and  WK  is  an  array  of  dimension  4m 
or  larger.  PHI  and  WK  are  work  spaces  for  the  routine. 

Error  Return.  IERR  =  I  if  n  <  1  or  n  >  mw,  and  IERR  =  3  if  some  t ut-  is  negative. 

Algorithm.  The  abscissas  Xi  corresponding  to  the  positive  weights  are  first  mapped  into 
values  in  the  interval  [-1,1].  Then  the  Forsythe  procedure  is  used. 

Programmer.  A.  H.  Morris 
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CUBIC  SPLINE  INTERPOLATION 


Given  <  •  •  •  <  xn.  A  function  /(x)  is  a  cubic  spline  having  the  nodes(knots ) 
xi ,  . . . ,  xn  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x,-,  x,+1]  for  *'  =  1,  . . . ,  n  -  1, 
and  the  first  and  second  derivatives  /'(x)  and  /"(x)  exist  and  are  continuous  for  all  x.  If 
fi  denotes  the  polynomial  for  the  interval  [a;,-,  then  fi  has  the  form: 

/.(*)  =  yi  +  a<(x  -  Xi)  +  bi(x  -  Xi)2  +  c*(x  -  x,)3. 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  f1}  /n_j  together 
at  the  points  x2,  . . .  For  x  <  /(x)  =  /x(x),  and  for  x  >  xn  f(x)  =  fn-i{x).  Also 

f(xi)  —  yi  for  *  =  1,  . . . ,  n  -  1.  Hence,  if  /(x„)  =  yn  then  /  interpolates  the  points  (x,-,  y^) 
for  t  =  1,  ,  n. 

Assume  now  that  the  ordinates  yi , . . . ,  y„  are  given.  Then  there  exist  an  infinitude 
of  splines  with  nodes  x\t  . . . ,  xn  that  interpolate  the  points  (x,-,yj).  In  general,  two  inde¬ 
pendent  conditions  must  be  imposed  to  uniquely  specify  the  interpolating  spline  /  which  is 
of  interest.  Frequently,  /  is  restricted  on  the  first  interval  [x1}x2]  by  requiring  that  f'{x i) 
or  f"(x i)  has  a  given  value,  or  that  /  is  continuous  at  x2.  Also,  /  is  restricted  on  the 
last  interval  [xn_j,xn]  by  requiring  that  f'{xn)  or  f"{xn)  has  a  given  value,  or  that  /  is 
continuous  at  xn_i.  The  subroutine  CBSPL  is  available  for  obtaining  the  spline  when  these 
restrictions  are  employed.  Alternatively,  /  may  be  required  to  satisfy  the  conditions 

/"(* i)  =  «/"(*2)  +  £  \a\  <  1 

/"(x„)  =  a/"(xn_ x)  +  fi  |a|  <  1 

when  n  >  4.  Then  the  subroutine  SPLIFT  is  available  for  obtaining  the  spline. 

CALL  CBSPL^F, A,B,C,n, t'i,t 2, wi,u>2,IERR) 

X  and  Y  are  arrays  containing  the  abscissas  n,  . . .  ,xn  and  ordinates  yi,  . . . ,  y„.  It  is 
assumed  that  xj  <  •  •  •  <  xn  and  n  >  3.  A,B  and  C  are  arrays  of  dimension  n  or  larger, 
and  IERR  an  integer  variable.  When  CBSPL  is  called  ,  if  no  input  errors  are  detected  then 
IERR  is  set  to  0.  Also,  the  coefficients  a,-,  ct-  (*  =  1,  . . . ,  n  —  1)  of  the  interpolating  spline 
f(x)  are  stored  in  A,B,C,  and  A(n)  is  set  to  /'(xn). 

The  arguments  *i,*2,  t»i,  tt>2  specify  the  conditions  that  the  spline  /(x)  must  satisfy.  It 
is  assumed  that  i  i  and  t2  have  the  values  0,1,2  where: 

*1=0  /is  continuous  at  x2.  t2  —  0  /is  continuous  at  xn—\. 

*i  =  1  has  the  value  tux-  *2  =  1  fi1*,)  has  the  value  u/n. 

*i  =  2  f"[x i)  has  the  value  u/x.  *2  =  2  /"(i„)  has  the  value  wn. 

If  *i  =0  then  the  argument  u»i  is  ignored,  and  if  »2  =  0  then  tu2  is  ignored. 

Error  Return.  IERR  =  1  if  n  <  3  and  IERR  =  2  if  x,-  >  x*+1  for  some  i. 
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Remarks. 


(1)  B(n )  and  C(n)  are  used  for  temporary  storage. 

(2)  If  i'i  =  x2  =  0  and  n  ==  3,  then  it  is  also  assumed  that  f'(x 2)  +  f'(x 3)  =  2 (^). 

(3)  After  A,  B  and  C  have  been  obtained,  then  SCOMP  or  SCOMP1  may  be  used  to 
evaluate  the  spline  at  any  point  x.  SEVAL  or  SEVAL1  may  be  used  if  derivatives  are 
also  desired. 

Programming.  CBSPL  is  an  adaptation  by  A.  H.  Morris  of  the  subroutine  CUBSPL, 
written  by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Verlag,  1978. 

CALL  SPLIFT(X,  Y,  DY,DDY,  n,  W,  IERR,MO,  a,  0,  a,  0) 

X  and  Y  are  arrays  containing  the  abscissas  x\,  . . . ,  xn  and  ordinates  t/i,  . . . ,  yn.  It  is 
assumed  that  X\  <  ■  ■  ■  <  xn  and  n  >  4.  DY  and  DDY  are  arrays  of  dimension  n  or  larger, 
and  IERR  an  integer  variable.  When  SPLIFT  is  called,  if  there  are  no  input  errors  then 
IERR  is  assigned  the  value  0,  the  first  derivatives  f'(xi),  ...,f'(xn)  are  computed  and 
stored  in  DY(1),  ...,DY(n),  and  the  second  derivaties  f"[x  1),  ...,f"(xn)  are  computed 
and  stored  in  DDY(l),  . . .  ,DDY(n). 

W  is  an  array  of  dimension  3n  or  larger  that  is  used  for  a  storage  area.  On  the  first  call 
to  SPLIFT  the  argument  MO  must  be  set  to  0.  When  SPLIFT  is  initially  called,  certain 
calculations  which  depend  only  on  the  values  of  a,  a ,  and  x\ ,  . . . ,  xn  are  performed  and  the 
results  stored  in  W.  On  subsequent  calls  to  SPLIFT,  if  only  values  of  /?,  /?  or  yi,  . . .  ,yn 
are  modified,  then  the  information  in  W  need  not  be  recomputed.  Set  MO  =  1  and  the 
information  in  W  will  be  reused. 


Error  Return  If  there  is  an  input  error  then  IERR  is  set  as  follows: 

IERR  =1  if  |a|  >  1  or  |a|  >  1. 

IERR  =  2  if  n  <  4. 

IERR  =  3  if  the  restriction  Xi  <  •  ■  ■  <  xn  is  not  satisfied. 

Remarks. 


(1)  After  DY  and  DDY  have  been  obtained,  then  SCOMP1  or  SCOMP2  may  be  used  to 
evaluate  the  spline  at  any  point  x .  SEVAL1  or  SEVAL2  may  be  used  if  derivatives  are 
also  desired. 

(2)  Given  the  values  y[  and  Then  there  exists  a  unique  interpolating  cubic  spline  / 
that  satisfies  /'(^i)  =  y[  and  f'(xn)  =  y'n.  This  spline  can  be  obtained  by  setting 
a  —  a  =  -1/2  and 


X2  —  Xi 


V2  ~  yi 
x2  -  Xi 


xn  Xn—i 


yn  -  yn-i 
xn  -  Z„_i 


Programmer.  Rondall  E.  Jones  (Sandia  Laboratories). 
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WEIGHTED  LEAST  SQUARES  CUBIC  SPLINE  FITTING 


Let  ti  <  •  •  •  <  ti  be  a  sequence  where  £  >  2,  {(a;,-,  y;)  :  i  =  1,  . . . ,  m}  be  a  set  of  m  >  4 
points  where  ti  <  x\  <  •  •  ■  <  xm  <  tL,  and  u>i,  be  positive  weights.  Then  the 

subroutine  SPFIT  is  available  for  obtaining  a  cubic  spline  f(x )  with  the  nodes  t1} 

tn 

which  minimizes  w*  (/(x»)  ~  Vi)2-  This  spline  is  represented  by 

«=i 


f{x)  =  Zj  +  aj{x  -  tj)  +  bj{x  -  tj )2  +  Cj{x  -  tjf 

for  ti  <  x  <  tj+ 1  (j  =  1,  1).  If  the  nodes  are  selected  so  that  l  <  m  —  2  and 

each  interval  i)  contains  a  data  point  xVjy  then  this  least  squares  approximation  is 

unique. 

CALL  SPFIT(X,  m,  T,  l,  Z,  A,  B,  C,  WK,IERR) 

X  is  an  array  containing  z1;  ...,xm,  Y  an  array  containing  y1}  W  an  array 

containing  w1}  and  T  an  array  containing  t1}  Z,A,B,C  are  arrays  of 

dimension  t  -  1  or  larger,  and  IERR  is  an  integer  variable.  When  SPFIT  is  called,  if  no 
input  errors  are  detected  the  IERR  is  set  to  0.  Also,  the  coefficients  Zj,aj,bj,c:-  of  the  least 
squares  approximating  spline  f(x)  are  computed  and  stored  in  Z,A,B,C. 

WK  is  an  array  of  dimension  7£  +  18  or  larger  that  is  a  work  space  for  the  routine. 

Error  Return.  IERR  is  set  to  one  of  the  following  values  when  an  input  error  is  detected. 
IERR  =  1  if  £  <  2. 

IERR  =  2  if  ti  <  ■  •  •  <  t(_  is  not  satisfied. 

IERR  =  3  if  m  >  4  and  t\  <  xi  <  —  <  xm  <  ti  are  not  satisfied. 

If  an  error  is  detected,  the  routine  immediately  terminates. 

Remark.  After  A,  B,  C,  and  Z  have  been  obtained,  them  SCOMP  may  be  used  to  evaluate 
the  spline  at  any  point  x.  SEVAL  may  be  used  if  derivatives  are  also  desired. 

Programming.  SPFIT  employs  the  subroutines  BSPP,  BSL2,  BSPEV,  BCHFAC,  and 
BCHSLV.  SPFIT  was  written  by  A.  H.  Morris. 
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CUBIC  SPLINE  EVALUATION 


Given  x\  <  •  •  •  <  xn.  A  function  f{x )  is  a  cubic  spline  having  the  nodes  {knots) 
xi,  . . .  ,xn  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [xi,Zi+i]  for  »  =  1,  . . .  ,n  -  1, 
and  the  first  and  second  derivatives  f'{x)  and  f"(x)  exist  and  are  continuous  for  all  x.  If 
fi  denotes  the  polynomial  for  the  interval  [z^,  £«+i]  then  /»  has  the  form: 

/<(*)  =  V«  +  <*»(*  -  +  M*  ~  xi?  +  «i(*  -  *<)3 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  /1(  i  together 

at  the  points  x2,  .  ..,xn_i.  For  x  <  xx  }{x)  —  fi{x),  and  for  x  >  xn  f(x)  =■•/„_ i(x). 
Also  f(xi)  =  y*  for  *  =  1,  . . .  ,rt  -  1.  Hence,  if  f{xn)  =  yn  then  /  interpolates  the  points 
{xi,yi)  for  i  =  1, 

A  cubic  spline  /  given  by  the  polynomials  /1;  is  uniquely  defined  by  any  of 

the  following  three  sets  of  data: 

(1)  the  points  (x»,  yi)  and  coefficients  a*,  c»  for  *  =  1,  . . . ,  n  —  1 

(2)  the  points  (x^,  y^)  and  first  derivatives  /'(i*)  for  *  =  1, . . . , n 

(3)  the  points  (x»,yj)  and  second  derivatives  /"(x^)  for  :  =  1,  . . .  ,n 

The  subroutines  SCOMP,  SCOMP1,  SCOMP2  are  available  for  computing  the  spline  at 
any  point  x.  SCOMP  is  used  if  data  set  (1)  is  given,  SCOMP1  is  used  if  data  set  (2)  is 
given,  and  SCOMP2  is  used  if  data  set  (3)  is  given. 

CALL  SCOMP {X,  Y,A,B,  C,  N, XI, YI,  m,  IERR) 

Let  N  =  n  -  1.  Then  N  is  the  number  of  polynomials  fi  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  x\,  ...,x^  and  ordinates  yt,  ...}yN,  and  A,B,C 
are  arrays  containing  the  coefficients  a*,  c,-  (t  =  1,  . . . ,  N).  It  is  assumed  that  N  >  1  and 

that  xi  <  ■  ■  •  <  xjv- 

Let  xi,  ...  ,xm  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  xi,  ... ,  xm,  YI  an  array  of  dimension  m  or  larger,  and  IERR  a  variable.  When 
SCOMP  is  called,  if  m  <  1  then  IERR  is  set  to  1  and  the  routine  terminates.  Otherwise,  if 
m  >  1  then  IERR  is  set  to  0  and  f(xj)  is  computed  and  stored  in  YI(j)  for  j  =  1,  . . . ,  m. 

Note.  SCOMP  does  not  require  /  to  be  a  spline.  It  is  only  required  that  /»(x)  be  a  cubic 
polynomial  y ,•  +  o,(x  -  Xi)  +  6j(x  -  xf)2  +  c,(x  -  xt)3  and  that 

f{x)  =  fi{x)  for  x  <  Xj 

f{x)  =  fi(x )  for  Xi  <  x  <  x,+i  (1  <  t  <  N) 

/(x)  =  /^(x)  for  x  >  xn. 

In  this  case,  SCOMP  computes  the  value  f{ij+ )  for  j  =  1,  . . . ,  m. 
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Laboratories). 

CALL  SCO M PI (X,  Y,  DY,  n,  XI, YI,  m,  IERR) 

X,  Y,  DY  are  arrays  containing  the  abscissas  xi, . . ., xn,  ordinates  t/i, . . .,  yn,  and  first 
derivatives  f'(x  i), . . .,  f'(xn)  respectively.  It  is  assumed  that  n  >  2  and  x\  <  ■  •  •  <  xn. 

Let  xi,  . . . ,  xm  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  x1}  . . . ,  xm,  YI  an  array  of  dimension  m  or  larger,  and  IERR  a  variable.  When 
SCOMP1  is  called,  if  m  <  1  then  IERR  is  set  to  1  and  the  routine  terminates.  Otherwise, 
if  m  >  1  then  IERR  is  set  to  0  and  f{xj)  is  computed  and  stored  in  YI(j)  for  j  =  1,  ...  ,m. 

Programming.  Adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones  (Sandia 
Laboratories). 

CALL  SCO  M  P2(X,  Y,  DDY,  n,  XI, YI,  m,  IERR) 

X,  Y,  DDY  are  arrays  containing  the  abscissas  ii, . . .,  xn,  ordinates  yi,..  .,yn  and 
second  derivatives  f  "(x i), . . .,  f"(xn)  respectively.  It  is  assumed  that  n  >  2  and  X\< •  •  • <xn . 

Let  xi,  ...  ,xm  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  x\,  . . . ,  xm,  YI  an  array  of  dimension  m  or  larger,  and  IERR  a  variable.  When 
SCOMP2  is  called,  if  m  <  1  then  IERR  is  set  to  1  and  the  routine  terminates.  Otherwise, 
if  m  >  1  then  IERR  is  set  to  0  and  }{xj)  is  computed  and  stored  in  YI(j)  for  j  =  1,  . . .  ,m. 

Programmer.  Rondall  E.  Jones  (Sandia  Laboratories) 


402 


CUBIC  SPLINE  EVALUATION  AND  DIFFERENTIATION 


Given  xx  <  •••  <  xn.  A  function  f(x)  is  a  cubic  spline  having  the  nodes  (knots) 
xi,  . . .  ,xn  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x»,xj+1]  for  i  =  1,  . . .  ,n  —  1, 
and  the  first  and  second  derivatives  f'(x)  and  f"(x)  exist  and  are  continuous  for  all  x.  If  /,• 
denotes  the  polynomial  for  the  interval  [xi,x,-+x]  then  /»  has  the  form: 

/<(*)  =  W  +  <*iix  “  xi)  +  bi(x  ~  xi)2  +  Ci(x  -  a;*)3 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  fx,  . . . ,  /n_x  together 
at  the  points  x2,  ■  •  • ,  *»-i-  For  x  <  xx  f(x)  =  fi(x),  and  for  x  >  xn  f(x)  =  fn~\(x).  Also 
/(**)  =  y,  for  *  =  1,  . . .  ,n  -  1.  Hence,  if  f(xn )  =  y„  then  /  interpolates  the  points  (xi,y,) 
for  i  =  1,  . . .  ,n. 

A  cubic  spline  /  given  by  the  polynomials  fx,  . . .  ,fn-i  is  uniquely  defined  by  any  of 
the  following  three  sets  of  data: 

(1)  the  points  (x,, y»)  and  coefficients  a<,6i,c<  for  t  =  1,  ...,»—  1 

(2)  the  points  (x,-,  y,)  and  first  derivatives  /'(xj)  for  f  =  1,  . . . ,  n 

(3)  the  points  (x^,  y,)  and  second  derivatives  /"(xj)  for  i  =  1,  . . . ,  n 

The  subroutines  SEVAL,  SEVAL1,  SEVAL2  are  available  for  computing  the  spline  and  its 
first  and  second  derivatives  at  any  point  x.  SEVAL  is  used  if  data  set  (1)  is  given,  SEVAL1 
is  used  if  data  set  (2)  is  given,  and  SEVAL2  is  used  if  data  set  (3)  is  given. 

CALL  SEVALpf,  Y,  A,  B,  C,  N, XI,YI,DYI,DDYI,  m,  IERR) 

Let  N  =  n  —  1.  Then  N  is  the  number  of  polynomials  /;  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  *i,  . . .  ,xp/  and  ordinates  yx,  . . . ,  y^,  and  A,  B,C  are 
arrays  containing  the  coefficients  a,-,  bi,  Cj(t  =  1,  . . . ,  N).  It  is  assumed  that  N  >  1  and  that 

X\  <  •  •  *  <  Xpf. 

Let  xx, ...  ,xm  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xx,  ...,  xm,  YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger,  and  IERR  is  a  variable.  When  SEVAL  is  called,  if  m  <  1  then  IERR  is  set  to 
1  and  the  routine  terminates.  Otherwise,  if  m  >  1  then  IERR  is  set  to  0  and  the  values 
f(xj),  f'(xj),  f"(xj)  are  computed  and  stored  in  YI (j),  DYI(j),  DDYI(ji)  for  j  =  1,  . . .  ,m. 

Note.  SEVAL  does  not  require  /  to  be  a  spline.  It  is  only  required  that  fi(x)  be  a  cubic 
polynomial  y,-  +  o,(x  -  Xj)  +  6x(x  -  Xj}2  +  Cj(x  -  x*)3  and  that 

f{x)  =fi{x)  for  x  <  xx 

/(x)  =/t(x)  for  Xi  <  x  <  x*+i  (1  <  t  <  N)  . 

f{x)  =fN{x)  for  x  >  iff. 

In  this  case,  SEVAL  computes  the  values  / (xy+),  f'{xj+),  /"(x3+)  for  j  =  1,  . . . ,  m. 
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CALL  SEVAL1(X,  Y,  DY,  n,  XI,YI,DYI,DDYI,  m,  IERR) 

X,  Y,  DY  are  arrays  containing  the  abscissas  xx,  . . . ,  xn,  ordinates  yx,  . . . ,  yn,  and  first 
derivatives  f'(x\ ),  . . . ,  /'(xn)  respectively.  It  is  assumed  that  n  >  2  and  x\  <  •  •  •  <  xn. 

Let  xi,  ...  ,xm  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xx,  . . . ,  xm,  YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger,and  IERR  is  a  variable.  When  SEVAL1  is  called,  if  m  <  1  then  IERR  is  set 
to  1  and  the  routine  terminates.  Otherwise,  if  m  >  1  then  IERR  is  set  to  0  and  the  values 
f[xj),  f(xj),f"(xj)  are  computed  and  stored  in  YI(j),  DYI(j),  DDYI(j')  for  j  =  1,  . . . ,  m. 

Programming.  Adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones  (Sandia 
Laboratories). 

CALL  SEVAL2(X, Y,  DDY,  n, XI, YI, DYI, DDYI,  m,  IERR) 

X,  Y,  DDY  are  arrays  containing  the  abscissas  Xi,...,xn,  ordinates  ylr..,yn,  and 
second  derivatives  /"(xj),. . . ,  f"(xn)  respectively.  It  is  assumed  that  n  >  2  and  xx<- •  •  <xn. 

Let  xi,  ...  ,xm  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xx,  . . .  ,xm,YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger, and  IERR  is  a  variable.  When  SEVAL2  is  called,  if  m  <  1  then  IERR  is  set 
to  1  and  the  routine  terminates.  Otherwise,  if  m  >  1  then  IERR  is  set  to  0  and  the  values 
f(xj),  f(xj),f”(xj)  are  computed  and  stored  in  YI(j'),  DYIfy),  DDYI(j)  for  j  =  I,  . . . ,  m. 

Programmer.  Rondall  E.  Jones  (Sandia  Laboratories) 
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INTEGRALS  OF  CUBIC  SPLINES 


Given  xx  <  •■•  <  xn.  A  function  f{x)  is  a  cubic  spline  having  the  nodes  (knots) 
xi ,  ,xn  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x*,  for  t  =  1,  . . . ,  n  —  1, 
and  the  first  and  second  derivatives  f'(x)  and  f"(x)  exist  and  are  continuous  for  all  x.  If  fi 
denotes  the  polynomial  for  the  interval  [xi,x,-+1]  then  fi  has  the  form: 

fi{x)  =  y,-  +  a,(x  -  +  bi(x  -  ii)2  +  c,(x  -  x,-)3 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  /1}  x  together 

at  the  points  x2,  xn_x.  For  x  <  xx  f(x )  =  /x(x),  and  for  x  >  x„  f(x)  =  /„_x(x).  Also 
/(*»)  ~  yi  for  *  =  1,  . ..  ,n  -  1.  Hence,  if  f(xn)  =  yn  then  /  interpolates  the  points  (x»,yj) 
for  *  =  1,  . . . ,  n. 

A  cubic  spline  /  given  by  the  polynomials  fi,  ...,  /n_x  is  uniquely  defined  by  any  of 
the  following  three  sets  of  data: 

(1)  the  points  (x,-,  yi)  and  coefficients  a^,  bi,  Ci  for  i  =  1,  . . . ,  n  —  1 

(2)  the  points  (xt-,yj)  and  first  derivatiyes  /'(x,-)  for  *  =  1,  ...,n 

(3)  the  points  (x,-,  yi)  and  second  derivatives  f"(xi)  for  t  =  1,  . . .  ,n 

For  any  real  a  and  /?  the  functions  CSINT,  CSINT1,  CSINT2  are  available  for  computing 
the  integral  f(i)dt.  CSINT  is  used  if  data  set  (1)  is  given,  CSINT1  is  used  if  data  set 
(2)  is  given,  and  CSINT2  is  used  if  data  set  (3)  is  given. 

CSINT(X,  Y,  A,  B,C,  N,  a,fi) 

Let  N  =  n  —  1.  Then  N  is  the  number  of  polynomials  fi  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  xx ,  ...,xN  and  ordinates  yi,  . .  - ,  yjy,  and  A,B,C  are 
arrays  containing  the  coefficients  o,-,  bi}  c,  (i  =  I,  . . . ,  N).  It  is  assumed  that  N  >  1  and  that 
x\  <  —  <  Xff.  Then  CSINT  has  the  value  J ^  f(t)  dt. 

Programming.  CSINT  calls  the  function  INTRVL.  CSINT  was  written  by  A.  H.  Morris. 
CSINT1(X,  Y,DY,  n,  a,  /?) 

X,  Y,  DY  are  arrays  containing  the  abscissas  xx,  ...,x„,  ordinates  yx,  . . . , yn,  and  first 
derivatives  f(x x),  ...,/'(i„)  respectively.  It  is  assumed  that  n  >  2  and  x1  <  <  xn. 

Then  CSINT1(X,  Y,DY,  n,  a,  /3)  =  f  (t )  dt. 

Programming.  CSINT1  calls  the  function  INTRVL.  CSINT1  was  written  by  A.  H.  Morris. 
CSINT2pf,  Y,DDY,  n,  a,  0) 

X,  Y,  DDY  are  arrays  containing  the  abscissas  xj, ordinates  ylr  ..,y„,  and 
second  derivatives  /"(xx),. . . ,  f"(xn)  respectively.  It  is  assumed  that  n  >  2  and  xx<-  •  •  <x„. 
Then  CSINT2(A,  Y, DDY,  n,  a,  f3)  =  f*  f(t)  dt. 

Programming.  CSINT2  calls  the  function  INTRVL.  CSINT2  was  written  by  A.  H.  Morris. 
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N-DIMENSIONAL  CUBIC  SPLINE  CLOSED  CURVE  FITTING 


Given  m  >  2  points  z,-  =  (z»i,  . .  .  ,x,„)  where  n  >  2.  One  procedure  for  fitting  a 
closed  curve  to  the  points  is  to  first  let  si  =  0, =  s»_i  +  ||x,-  —  x,_i ||  for  i  =  2,  ...  ,m,  and 
Sm+i  =  +  ||zi  -  Zmll,1  next  let  t,-  =  Si/sm+i  for  t  =  1,  .. . ,  m  +  1,  and  then  to  find  for 

each  j  <n  the  periodic  cubic  spline  7j(t)  having  the  knots  ii,  . . .  ,tm+i  where  7y(tj)  =  x*y 
for  i  <  m.  The  mapping  7 (t)  =  (71  (t),  . . .  ,7n(t))  then  defines  on  the  interval  [0, 1]  a  closed 
curve  which  traverses  the  points  (ti ,  zi),  . . . ,  (fm,  zm),  (1,  Zi)  and  satisfies  7/(0)  =  7'(l)  and 
7#/(0)  =  7,,(1).  For  t  <  0  and  t  >  1,  7(f)  is  defined  by  periodicity  (having  period  1).  The 
subroutine  CSLOOP  is  available  for  obtaining  the  derivatives  7y(tt)  which  characterize  this 
curve,  the  subroutine  LOPCMP  is  available  for  computing  the  curve,  and  the  subroutine 
LOPDF  is  available  for  differentiating  the  curve. 

CALL  CSLOOP(m,  n, X,  kx,  T,  DX,  kdx,  WK,IERR) 

X  is  an  m  x  n  matrix  whose  *th  row  contains  the  point  z,-  =  (z^i,  . . . ,  z,n),  where  m  >  2 
and  n  >  2.  It  is  assumed  that  the  points  zi,  . . . ,  xm  are  indexed  in  the  order  that  they  are 
to  be  traversed  by  the  curve  7(t).  It  is  also  assumed  that  z,-  yt  zt+ 1  for  t  =  1,  . . .  ,m  —  1 
and  that  zm  ^  zi . 

DX  is  a  2-dimensional  array  containing  at  least  m  rows  and  n  columns.  The  arguments 
kx  and  kdx  have  the  following  values: 

kx  =  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  =  the  number  of  rows  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  required  that  kx>  m  and  kdx  >  m. 

IERR  is  a  variable  and  T  an  array  of  dimension  m  or  larger.  When  CSLOOP  is  called,  if 
no  input  errors  are  detected  then  IERR  is  assigned  the  value  0  and  ...  ,tm  are  computed 
and  stored  in  T.  Also,  the  derivatives  7'(t,-)  are  computed  and  stored  in  DX,  where  the  tth 
row  of  DX  contains  i{U)  =  (71  (**)>  •  -  -  >  7^(£*))- 

WK  is  an  array  of  dimension  4 (m  —  1)  or  larger  that  is  a  work  space  for  the  routine. 

Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =1  ifm<2orn<2 
IERR  =  2  if  Zj  =  zl+1  for  some  i. 

IERR  =  3  if  zi  =  xm. 

Remark.  After  T  and  DX  are  obtained,  LOPCMP  may  be  used  to  compute  the  curve  and 
LOPDF  may  be  used  to  differentiate  the  curve. 

Programming.  CSLOOP  calls  the  subroutine  CSLOP1  and  function  SNRM2.  CSLOOP 
and  CSLOP1  were  written  by  A.  H.  Morris. 

1 11*11  =  for  any  *  =  (*i ,  . . . ,  xm)- 
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CALL  LOPCMP(m,  n,  T,  X,  kx,  DX,  kdx,£,  TI,  Z,  kz) 

T  is  an  array  containing  the  knots  t1}  . . . ,  tm,  X  an  m  X  n  matrix  whose  » th  row  contains 
the  point  a and  DX  an  m  X  n  matrix  whose  tth  row  contains  the  derivative  The 

arguments  kx  and  kdx  have  the  following  values: 

kx  =  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  =  the  number  of  rows  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  assumed  that  m  >  2,  n  >  2,  kx  >  m,  and  kdx  >  m. 

Let  t\  ,  . . . ,  ti  be  the  points  at  which  the  curve  7  is  to  be  evaluated.  TI  is  an  array 
containing  t\,  ... ,  ti,  and  Z  a  2-dimensional  array  containing  at  least  l  rows  and  n  column?. 
The  argument  kz  is  the  row  dimension  for  Z  in  the  calling  program.  It  is  assumed  that 
£  >  1  and  kz  >  1.  When  LOPCMP  is  called,  7(t,-)  =  (71  (£») ,  . . .  ,7 „(£,•))  is  computed  and 
stored  in  the  »th  row  of  Z  for  t  =  1, 

Programmer.  A.  H.  Morris 

CALL  LOP DF(m,  n,  T,  X,  kx,  DX,  kdx,  t0,  Z,  DZ,DDZ) 

T  is  an  array  containing  the  knots  t1}  . . .  ,tm,  I  an  mx  n  matrix  whose  »th  row 
contains  the  point  Xi,  DX  an  m  X  n  martrix  whose  xth  row  contains  the  derivative  7 '{ti). 
The  arguments  kx  and  kdx  have  the  following  values: 

kx  =  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  =  the  number  of  rows  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  assumed  that  m  >  2,  n  >  2,  kx  >  m,  and  kdx  >  m. 

Z,  DZ,  and  DDZ  are  arrays  of  dimension  n.  For  any  real  t0, 7(io)  =  (71  (*o),  •  •  • ,  7n(*o))) 
7'(*o)  =  (7i(fo)>  ■■■>7n(to)),  and  7"(to)  =  (li(to),  ■■■,7n(to))  are  computed  and  stored 
in  Z,  DZ,  and  DDZ  respectively. 

Programmer.  A.  H.  Morris 
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SPLINE  UNDER  TENSION  INTERPOLATION 

Given  real  a  and  xi  <  •  •  •  <  xn.  A  function  f(x)  is  a  spline  having  the  tension  factor 
a  and  the  nodes  {knots)  xi,  ...  ,xn  if  f(x)  and  its  first  two  derivatives  are  continuous  on 
[xi,x„],  and  f"{x)  -  o2f{x)  =  a,z  +  on  the  interval  [z,-,z<+1]  for  t  =  1,  ... ,n  -  1. 
Here  a  =  \cr\  (n  —  1  )j[xn  —  xi)  and  a*,  6,-  are  constants.  For  x ,■  <  x  <  xt+i  /(x)  can  be 
represented  by 

/(x)  =  Asinha(x  -  x^  +  R,  sinha(z,+1  -  x)  -  {aix  +  b^/o2 

when  a  ^  0,  and  by  a  cubic  polynomial  when  <7  =  0. 

Assume  now  that  n  ordinates  y1(  . . . ,  y„  are  given.  Then  there  exist  an  infinitude  of 
splines  /(x)  having  tension  a  for  which  f{xi)  =  y*  (t  =  1,  ...,n).  However,  if  values  yi 
and  y'n  are  given  then  only  one  of  these  splines  will  satisfy  f'(xi)  =  yi  and  f'{xn)  =  y^. 
For  convenience,  denote  this  spline  by  fa.  If  a  =  0  then  it  is  clear  that  fa  is  the  standard 
cubic  spline.  Also  it  can  be  verified  that  when  a  — *  oo,  fa  converges  uniformly  on  [xj,xnj 
to  the  piecewise  linear  function  £{x)  where  £(x)  =  y»  +  m,(x  —  x»)  for  x»  <  x  <  x»+1 

(*  =  1,  . . . ,  n  —  1).  Here  m,  =  (y,+i  —  yi)/(x,+1  -  Xj).  The  following  subroutine  is  available 

for  obtaining  the  spline  fa . 

CALL  CURV1  (n,  X, Y,  SLP1,SLPN,IND,DDY,TEMP, <r, IERR) 

X  and  Y  are  arrays  containing  the  abscissas  xi,  . . . ,  xn  and  ordinates  yi,  . . . ,  yn.  It  is 
assumed  that  n  >  2  and  ij  <  •  ■  ■  <  xn. 

SLP1  and  SLPN  are  assigned  the  values  yj  and  y^.  The  user  may  omit  values  for 
either  or  both  of  these  arguments.  IND  specifies  the  information  that  is  provided. 

IND  =  0  Values  are  supplied  for  SLP1  and  SLPN. 

IND  =  1  A  value  is  supplied  for  SLP1  but  not  for  SLPN. 

IND  =  2  A  value  is  supplied  for  SLPN  but  not  for  SLP1. 

IND  =  3  Values  are  not  supplied  for  SLP1  and  SLPN. 

If  a  value  is  not  supplied  by  the  user,  then  the  routine  provides  a  value. 

DDY  is  an  array  of  dimension  n  or  larger,  and  IERR  is  an  integer  variable.  When 
CURV1  is  called,  if  no  input  errors  are  detected  then  IERR  is  assigned  the  value  0  and  the 
second  derivatives  f"[x x),  . . . ,  f"{xn)  are  computed  and  stored  in  DDY. 

TEMP  is  an  array  of  dimension  n  or  larger  that  is  used  for  a  work  space. 

Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =  1  if  n  <  2. 

IERR  =  2  if  xi  <  ■  •  •  <  xn  is  not  satisfied. 

When  either  of  these  errors  is  detected,  the  routine  immediately  terminates. 
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Remarks. 

(1)  After  DDY  is  obtained  then  CURV2  may  be  used  to  evaluate  the  spline  at  any  point  x. 

(2)  X,  Y,  n,  SLP1,  SLPN,  IND,  a  are  not  modified  by  CURV1. 

Programming.  CURV1  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  CURV1, 
CEEZ,  and  TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 

Reference.  Cline,  A.  K., “Scalar  and  Planar  Valued  Curve  Fitting  using  Splines  under 
Tension,”  Comm.  ACM  17  (1974),  pp.  218-220. 
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SPLINE  UNDER  TENSION  EVALUATION 


Given  cr  and  x\  <  •  •  •  <  xn.  A  function  f(x)  is  a  spline  having  the  tension  factor 
o  and  the  nodes  (knots)  xi,  . . . ,  xn  if  f(x)  and  its  first  two  derivatives  are  continuous  on 
[xi,  xn],  and  f"(x)  —  ff2/(x)  =  a,x  +  bi  on  the  interval  [x,-,  x<+i]  for  *  =  1,  . . .  ,n  —  1.  Here 
a  =  |crj(n-  1  )/(in  —  xi)  and  are  constants.  If  /(x)  =  /i(x)  for  x,<x<x»+1  then  A(x) 
can  be  represented  by 


fi(x)  =  A,  sinh o(x  -  x.)  +  S,-smher(x,+1  -  x)  -  (a{x  +  b^/o2 


when  a^O,  and  by  a  cubic  polynomial  when  a  =  0.  For  x  <  xx  we  let  /(x)  =  /i(x),  and  for 
x  >  xn  we  let  f(x)  =  /„_ x(x). 

Assume  now  that  /(x,)  =  yx  for  i  =  1,  Then  for  a  fixed  cr,/(x)  is  uniquely 

defined  by  the  points  (x*,^)  and  the  second  derivatives  /"(x,-)(t  =  1,  When  this 

data  is  available,  the  following  function  may  be  used  to  compute  the  spline  at  any  point  t. 

CURV2(£,  n,  X,  Y,  DDY,  cr) 

X  and  Y  are  arrays  containing  the  abscissas  xl5  . . . ,xn  and  ordinates  yx,  . . .  ,yn,  and 
DDY  is  an  array  containing  the  second  derivatives  f"(x i),  . . . ,  f"(xn).  It  is  assumed  that 
n> 2  and  Xi  <  —  <  xn.  CURY2(i,  n,  X,  Y,  DDY,c)  =  f(t)  for  any  real  t. 

Remark.  After  DDY  has  been  obtained,  CURV2  may  be  repeatedly  called  to  evaluate 
the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However,  if  a  is 
modified  then  the  derivative  information  in  DDY  will  have  to  be  recomputed  before  CURV2 
can  be  used  with  the  new  tension  factor. 

Programming.  CURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  CURV2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 

Reference.  Cline,  A.  K.,  “Scalar  and  Planar  Valued  Curve  Fitting  using  Splines  under 
Tension,”  Comm.  ACM  17  (1974),  pp.  218-220. 
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DIFFERENTIATION  AND  INTEGRATION  OF  SPLINES  UNDER  TENSION 

Let  f(x)  be  a  spline  having  the  tension  factor  a  and  the  nodes  xi,  ... ,  xn.  Assume  that 
/(xi)  =  y<  for  i  =  1,  If  the  second  derivatives  /"(zi),  ...,/"(x„)  are  known  then 

the  following  functions  may  be  used  for  differentiating  and  integrating  the  spline. 

CURVD(t,  n,  X,  Y,  DDY,  <r) 

X  and  Y  are  arrays  containing  the  abscissas  x\,  . . . ,  xn  and  ordinates  t/i,  . .  ,,yn,  and 
DDY  is  an  array  containing  the  second  derivatives  /"(xj),  . . .  It  is  assumed  that 

n  >  2  and  xi  <  •  ••  <  xn.  For  any  real  t,  the  derivative  f'(t)  is  computed  and  assigned  to 
be  the  value  of  CURVD(f,  n,  X,  Y,  DDY,  a). 

Programming.  CURVD  employs  the  function  INTRVL  and  subroutine  SNHCSH.  CURVD 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 

CURVI(a,  b,  n,  X,  Y,  DDY,  a) 

X  and  Y  are  arrays  containing  the  abscissas  ...  ,xn  and  ordinates  y1}  ...  ,yn,  and 
DDY  is  an  array  containing  the  second  derivatives  /"(xx),  ... ,  f"{xn).  It  is  assumed  that 
n  >  2  and  *!<•••<  xn.  CURVI(a,6,  n,X,Y, DDY, cr)  =  /*  f(t)dt  for  any  real  a  and  b. 

Note.  It  is  not  required  that  a  <  b. 

Programming.  CURVI  employs  the  function  INTRVL  and  subroutine  SNHCSH.  CURVI 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 
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TWO  DIMENSIONAL  SPLINE  UNDER  TENSION  CURVE  FITTING 


Given  a  sequence  of  points  (zi,  yx),  . . . ,  (zre,y„).  One  procedure  for  fitting  a  curve  to 
the  points  is  to  let  sx  =  0  and  s*  =  e,_i  +  yj{Xi  -  zt_1)2  +  (y^  -  y,_i)2  for  i  =  2 ,...,«, 
and  then  to  find  two  splines  z(s)  and  y(s)  with  tension  a  that  satisfy  z(st)  =  z<  and 
y(s,)  =  y»  for  t  =  1,  . . . ,  n.  If  &i  and  9n  are  the  desired  angles  for  the  curve  s  (-►  (z(s),  y(s)) 
at  the  points  (si,yi)  and  (a:„,yn),  then  the  splines  x(s)  and  y(s)  can  be  selected  so  that 
z'(s»)  =  cos  0,  and  y'(s,)  =  sin#*  for  *  =  l,n.  The  curve  a  (z(s),y(s))  then  passes 
through  the  points  (z,-,y,)  and  has  the  required  slopes  at  the  end  points.  The  subroutine 
KURV1  is  available  for  obtaining  the  second  derivatives  z"(ei),y"(si)(i  =  1,  . . .  ,n)  which 
characterize  this  curve,  and  the  subroutine  KURV2  is  available  for  computing  the  curve. 

CALL  KU RVl(n, X, Y,  SLP1,SLPN,IND,DDX,DDY,TEMP, S,  <r, IERR) 

X  and  Y  are  arrays  containing  the  abscissas  x1}  . . .  ,z„  and  ordinates  y1?  . . .  ,yn.  It  is 
assumed  that  n  >  2  and  that  the  points  (xi,  y<)  are  indexed  in  the  order  that  they  are  to  be 
traversed  by  the  curve.  It  is  also  assumed  that  ( z< ,  y*)  ^  (z,+1,yi+1)  for  i  =  1,  . . . ,  n  —  1. 

SLP1  and  SLPN  are  assigned  the  values  9i  and  9n.  These  angles  are  measured  counter¬ 
clockwise  (in  radians)  from  the  positive  x-axis.  The  user  may  omit  values  for  SLP1  and/or 
SLPN.  IND  specifies  the  information  that  is  provided. 

IND  =  0  Values  are  supplied  for  SLP1  and  SLPN. 

IND  =  1  A  value  is  supplied  for  SLP1  but  not  for  SLPN. 

IND  =  2  A  value  is  supplied  for  SLPN  but  not  for  SLP1. 

IND  =  3  Values  are  not  supplied  for  SLP1  and  SLPN. 

If  a  value  is  not  supplied  by  the  user,  then  the  routine  provides  a  value. 

a  is  the  tension  factor  to  be  employed.  If  |<r|  is  small,  say  |cr|  <  10-3,  then  z(s)  and 
y(s)  approximate  cubic  splines.  Otherwise,  if  |c|  is  large,  say  |<rj  >  100,  then  the  resulting 
curve  approximates  the  polygonal  line  from  (xi,yi)  to  (zn, yn). 

IERR  is  an  integer  variable  and  5,  DDX,  DDY  are  arrays  of  dimension  n  or  larger. 
When  KURV1  is  called,  if  no  input  errors  are  detected  then  IERR  is  assigned  the  value 
0  and  the  values  sj,  ...,sn  are  computed  and  stored  in  S.  Also,  the  second  derivatives 
z"(si),  . . .  ,z"(s„)  and  y"(si),  . . . ,  y"(sn)  are  computed  and  stored  in  DDX  and  DDY. 

TEMP  is  an  array  of  dimension  n  or  larger  that  is  used  for  a  work  space. 

Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =  1  if  n  <  2. 

IERR  =  2  if  (z,-, y»)  =  (z,+i,yi+1)  for  some  ». 

When  either  of  these  errors  is  detected,  the  routine  immediately  terminates. 

Remark.  After  S,  DDX,  DDY  are  obtained,  KURV2  may  be  used  to  compute  the  curve. 

Programming.  KURV1  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  KURV1, 
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CEEZ,  and  TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 

CALL  KU RV2(t, XT,YT, n,X,Y, DDX, DDY, S, a) 

X  and  Y  are  arrays  containing  the  abscissas  x\,  ...,xn  and  ordinates  yls  .  ..,yn,  S 

is  an  array  containing  si, _ ,  sn,  and  DDX  and  DDY  are  arrays  containing  the  second 

derivatives  x"(si),  . . . ,  x"(s„)  and  y"(si),  . . . ,  y"(sn). 

Now  consider  the  change  of  variables  t  =  s/sn,  and  let  t  (i(i),y(t))  denote  the  curve 
in  terms  of  the  new  parameter  t.  XT  and  YT  are  real  variables.  For  any  0  <  t  <  1,  KURV2 
computes  the  point  (x(t),y(t))  on  the  curve  and  assigns  XT  the  value  x(t)  and  YT  the  value 
y{t). 

Remark.  After  DDX  and  DDY  have  been  obtained,  KURV2  may  be  repeatedly  called  to 
evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However, 
if  cr  is  modified  then  the  derivative  information  in  DDX  and  DDY  will  have  to  be  recomputed 
before  KURV2  can  be  used  with  the  new  tension  factor. 

Programming.  KURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  KURV2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 
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TWO  DIMENSIONAL  SPLINE  UNDER  TENSION 
CLOSED  CURVE  FITTING 


Given  n  >  2  points  (xi,yi),  . . . ,  (sn,yn).  One  procedure  for  fitting  a  closed  curve  to  the 
points  is  to  let  s x  =  ^(*1  -*»)“  + (»i  -v»)2  and  =  «»-i  +  y/{*i  -  +  (v,-  -  y,_i)2  for 

« ’  =  2,  . . . ,  n,  and  then  to  find  periodic  splines  x(s)  and  y(s)  with  tension  a  that  pass  through 
the  points  (si,zi),  . . . , (sn, zn), (sx  +  an,xx)  and  («i,yi),  ...,(s„,y„),(si  +  sn,y!).  The 
mapping  s  »-»•  (x(s),y(s))  then  defines  a  closed  curve  that  passes  through  the  points 
The  subroutine  KURVP1  is  available  for  obtaining  the  second  derivatives  x"(s*),  y w  (*»)(*'  = 
1,  . , . ,  n)  which  characterize  this  curve,  and  the  subroutine  KURVP2  is  available  for  com¬ 
puting  the  curve. 

CALL  KURVPl(n, X,  Y,  DDX,DDY,TEMP,  S, a,  IERR) 

X  and  Y  are  arrays  containing  the  abscissas  x\,  . . . , xn  and  ordinates  yi,  . . . , yn.  It  is 
assumed  that  n  >  2  and  that  the  points  (x*,yi)  are  indexed  in  the  order  that  they  are  to  be 
traversed  by  the  curve.  It  is  also  assumed  that  (x,-,  y»)  ^  (x,+1,yt+1)  for  t  =  1,  1. 

cr  is  the  tension  factor  to  be  employed.  If  \a\  is  small,  say  jcr|  <  10-3,  then  x(s)  and 
y(s)  approximate  periodic  cubic  splines.  Otherwise,  if  \a\  is  large,  say  \<j\  >  100,  then  the 
curve  approximates  the  closed  polygonal  path  that  traverses  the  points  (xi,y,). 

IERR  is  an  integer  variable  and  S,  DDX,  DDY  are  arrays  of  dimension  n  or  larger. 
When  KURVP1  is  called,  if  no  input  errors  are  detected  then  IERR  is  assigned  the  value 
0  and  the  values  ...,s„  are  computed  and  stored  in  S.  Also,  the  second  derivatives 
x"(si),  . . .  ,z"(sn)  and  y"(si),  . . . ,  y"(sn)  are  computed  and  stored  in  DDX  and  DDY. 

TEMP  is  an  array  of  dimension  2n  or  larger  that  is  used  for  a  work  space. 

Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =  1  if  n  <  2. 

IERR  =  2  if  (x»,y,)  =  (x,+i,  yi+i)  for  some  t. 

When  either  of  these  errors  is  detected,  the  routine  immediately  terminates. 

Remark.  After  S,  DDX,  DDY  are  obtained,  KURVP2  may  be  used  to  compute  the  curve. 

Programming.  KURVP1  employs  the  subroutines  TERMS  and  SNHCSH.  KURVP1  and 
TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 

CALL  KU  RVP2(t,  XT,YT,  n,  X,  Y,  DDX, DDY,  S,  a) 

X  and  Y  are  arrays  containing  the  abscissas  z1}  ...,x„  and  ordinates  yu  ...,y„,  S 
is  an  array  containing  si,  ...,sn,  and  DDX  and  DDY  are  arrays  containing  the  second 
derivatives  x"(si),  ...,s"(s„)  and  y"(si),  ...,y"(sn). 


417 


Now  consider  the  change  of  variables  t  =  (s  —  si)/sn,  and  let  t  h->  (x(t),y(t))  denote 
the  curve  in  terms  of  the  new  parameter  t.  Then  t  i— ►  (x(t),y(t))  maps  0  and  1  onto  the 
point  (®i,yi),  and  t  >— ►  (x(i),y(t))  is  a  periodic  function  (with  period  1). 

XT  and  YT  are  real  variables.  For  any  real  t,  KURVP2  computes  the  point  (x(£),y(t)) 
on  the  curve  and  assigns  XT  the  value  x(i)  and  YT  the  value  y(f). 

Remark.  After  DDX  and  DDY  have  been  obtained,  KURVP2  may  be  repeatedly  called  to 
evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However, 
if  a  is  modified  then  the  derivative  information  in  DDX  and  DDY  will  have  to  be  recomputed 
before  KURVP2  can  be  used  with  the  new  tension  factor. 

Programming.  KURVP2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  KURVP2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 
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THREE  DIMENSIONAL  SPLINE  UNDER  TENSION  CURVE  FITTING 


Given  n  >  2  points  (zi, yx, zi),  .  ..,(zn,yn,2n).  One  procedure  for  fitting  a  curve  to 
the  points  is  to  let  «x  =  0  and  Si  =  s,_x  +  yj{ii  -  z,_i)3  +  (y,-  -  y*_x )3  +  (z<  -  z,_x)J  for 
i  =  2,  and  then  to  find  splines  z(s), y(s),  z(s)  with  tension  a  that  satisfy  z(sj)  = 

*.•»  y(«.)  =  Vi,  and  z(si)  =  z,-  for  t  =  1,  . . . ,  n.  If  (zi , y 'uz[)  and  (x'n,  y'n, z'n ),  are  the  desired 
slopes  for  the  curve  s  (z(s),  y(s),  z(s))  at  the  points  (zi,  yx,zx)  and  (z„,  yn,  zn),  then  the 
splines  z(s),y(s),  z(s)  can  be  selected  so  that  z'(at)  =  x'it  y'(s,-)  =  y<,  and  z'(st)  =  z<  for 
t  =  l,n.  The  curve  s  ►-»  (z(s),  y(s),z(s))  then  passes  through  the  points  (zi,y»,z,)  and  has 
the  required  slopes  at  the  end  points.  The  subroutine  QUR.V1  is  available  for  obtaining  the 
second  derivatives  y"(s,-), (t  =  1,  ...,n)  which  characterize  this  curve,  and 

the  subroutine  QURV2  is  available  for  computing  the  curve. 

CALL  QURVl(n,  X,  Y,  Z,  SLP1X,SLP1Y,SLP1Z,SLPNX,SLPNY, 
SLPNZ,IND,DDX,DDY,DDZ,TEMP,  S,  a,  IERR) 

X  is  an  array  containing  Zi,  ...,xn,  Y  an  array  containing  yi,  ...,yn,  and  Z  an  ar¬ 
ray  containing  z\,  ...  ,zn.  It  is  assumed  that  n  >  2  and  that  the  points  (zi,y,-,z,)  are 
indexed  in  the  order  that  they  are  to  be  traversed  by  the  curve.  It  is  also  assumed  that 
(*»,  Vi,  for  i  =  1, . . .  ,n  -  1. 

SLP1X,  SLP1Y,  SLP1Z  and  SLPNX,  SLPNY,  SLPNZ  are  assigned  the  values  x[,  y\,  z[ 
and  z{,,y^,zj,.  The  user  may  omit  values  for  SLP1X,  SLP1Y,  SLP1Z  and/or  SLPNX, 
SLPNY,  SLPNZ.  The  argument  IND  specifies  the  information  that  is  provided. 

IND  =  0  Values  are  supplied  for  SLP1X,SLP1Y,SLP1Z  and  SLPNX, SLPNY, 

SLPNZ. 

IND  =  1  Values  are  supplied  for  SLP1X,  SLP1Y,SLP1Z  but  not  for  SLPNX, 

SLPNY,  SLPNZ. 

IND  =  2  Values  are  supplied  for  SLPNX, SLPNY, SLPNZ  but  not  for  SLP1X, 

SLP1Y,  SLPIZ. 

IND  =  3  No  values  are  supplied  for  SLP1X,  SLP1Y,  SLPIZ  and  SLPNX, 

SLPNY,  SLPNZ. 

If  a  value  is  not  supplied  by  the  user,  then  the  routine  provides  a  value. 

a  is  the  tension  factor  to  be  employed.  If  |cr |  is  small,  say  |cr|  <  10~3,  then  z(s),  y(s),  z(s) 
approximate  cubic  splines.  Otherwise,  if  \a\  is  large,  say  jcrj  >  100,  then  the  resulting  curve 
approximates  the  polygonal  line  from  (z^y^zx)  to  (z„,yn,z„). 

IERR  is  an  integer  variable  and  S,  DDX,  DDY,  DDZ  are  arrays  of  dimension  n  or 
larger.  When  QURV1  is  called,  if  no  input  errors  are  detected  then  IERR  is  assigned  the 
value  0  and  the  values  sx,  . . . ,  sn  are  computed  and  stored  in  S.  Also,  the  second  derivatives 
z"(3*)  («  =  1,  •••,«)  are  computed  and  stored  in  DDX,  DDY,  DDZ. 

TEMP  is  an  array  of  dimension  n  or  larger  that  is  used  for  a  work  space. 
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Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =  1  if  n  <  2. 

IERR  =  2  if  (xi,yi,Zi)  =  (xi+1,  for  some  i. 

When  either  of  these  errors  is  detected,  the  routine  immediately  terminates. 

Remark.  After  S ,  DDX,  DDY,  DDZ  are  obtained,  QURV2  may  be  used  to  compute  the 
curve. 

Programming.  QURV1  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  QURV1, 
CEEZ,  and  TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 

CALL  QURV2(t,  XT,YT,ZT,  n,X,  Y,  Z,  DDX, DDY, DDZ,  S,  a) 

A  is  an  array  containing  *i,  . . .  ,xn,  Y  an  array  containing  yi,  . . .  ,yn,  and  Z  an  array 
containing  z\ ,  ...  ,zn.  S  is  an  array  containing  sj,  . . .  ,sn  and  DDX,  DDY,  DDZ  are  arrays 
containing  the  second  derivatives  a y" (s») ,z" (s,)  (t  =  1,  . . . ,  n). 

Now  consider  the  change  of  variables  t  =  s/sn  and  let  t  (x(t),y{t),z(t))  denote  the 
curve  in  terms  of  the  new  parameter  t.  XT,  YT,  ZT  are  real  variables.  For  any  0  <  t  <  1, 
QURV2  computes  the  point  (x(i),t/(t),2(t))  on  the  curve  and  assigns  XT,  YT,  ZT  the 
values  x(t),y(t),z(t). 

Remark.  After  DDX,  DDY,  DDZ  have  been  obtained,  QURV2  may  be  repeatedly  called 
to  evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed. 
However,  if  a  is  modified  then  the  derivative  information  in  DDX,  DDY,  DDZ  will  have  to 
be  recomputed  before  QURV2  can  be  used  with  the  new  tension  factor. 

Programming.  QURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  QURV2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 
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B-SPLINES 


For  k  >  1  let  f{t)— {t  —  x)fc  1  when  t  >  x  and  /(t)=0  when  t  <x.  Then  for  any  sequence 
U<-  ••<*,■+*  where  let  Bik(x)=(ti+k-ti)f[ti,. . .  ,ii+fc]  where  /[*,-, . . .  ,ti+k]  is  the 

Ath  order  divided  difference  of  }(t).  The  function  Bik  is  called  a  B- spline  of  order  k.  For 
k  =  1  it  follows  that 


if  t,  <  x  <  i<+1 
otherwise 


More  generally,  for  k  >  2  Bik(x)  =  0  when  x  £  For  t,  <  x  <  ti+k 


when  ti  =  •  •  ■  =  and 


when  ti+ 1  =  •  •  •  =  ti+k. 


Otherwise,  if  no  point  appears  more  than  k  -  1  times  in  the  sequence  {ij, . . .  ,U+k}  then 


Bik(x)  - 


x  —  ti 
ti+k—  1  —  ti 


Bi,k-i{x)  + 


tj+k  ~  x 
ti+k  ~  ii+1 


£»+i,k-i(aO- 


From  these  relations  it  follows  that  Bik(x)  >  0  when  i,  <  x  <  ti+k.  Now  let  &  <  •  •  ■  <  £. 
be  the  distinct  points  in  {ti,  . . .  ,ti+k},  where  fy  appears  m3 ■  times  for  j  =  1, ...  ,r.  Then 
it  can  be  verified  that  Bik  is  a  polynomial  of  order  <  k  (degree  <  k  -  1)  on  each  interval 
[£j>  &+i)  (i '  =  1)  ■  •  • . r  ~  1),  and  that  Bik  is  of  class  Ck~m> -1  at  £y  for  j  =  1,  . . . ,  r. 

We  note  in  passing  that  if  t,(*  =  0,±1,±2,  ...)  is  a  sequence  where  t,-  <  fy+1  and 
U  <  ti+k  for  each  t,  then  for  any  x  €  [t3-,t3-+ 1),  Bik(x)  #  0  only  when  i  =  j  -  k+1,  ...  ,j. 
Moreover,  it  can  be  verified  that  Y*iBik(x)  =  1. 


Now  let  <  •  •  •  <  be  a  sequence  of  points,  which  we  shall  call  knots  or 
break  points.  If  £  >  2  then  f2)  •••>  &  will  be  called  the  interior  knots.  For  each  in¬ 
terior  knot  £y  let  there  be  associated  an  integer  my  >  1,  called  the  multiplicity  of  the  knot. 

Then  for  any  k  >  max  (m2,  . . . ,  let  *!<■••<  tn+k  (n  =  k  +  m2  H - h  mt)  be  any 

sequence  where 


(1)  «!<••■  <**  =  &, 

(2)  tk+ 1,  ...  ,tn  are  the  interior  knots,  where  each  interior  knot  £y  appears  exactly 
my  times,  and 

(3)  &+i  =  tn+i  <  * 1 2 3  *  <  tn+k. 


Otherwise,  if  £  —  1  then  for  k  >  1  let  tj  <  •  •  •  <  tn+k  (n  =  A)  be  any  sequence  where 
ii  <  *  *  •  <  tk  =  and  f2  =  tn+1  <  •  •  •  <  tn+k.  Then  for  £-  >  1,  we  note  that 
Bik,  •  •  •  >  Bnk  are  the  only  B-splines  of  order  k  which  need  not  be  0  on  the  interval 
Let  Pk[tk,  . . .,  £n+i]  denote  the  collection  of  all  piecewise  polynomials  p(x)  defined  on  the 
interval  [tfc,tn+i)  where  p(x)  is  a  polynomial  of  order  <  k  (degree  <  k  -  1)  on  (£y,£y+i) 


421 


for  j  =  1,  . . . ,  t,  and  p(x)  is  of  class  C'fc-m,'_1  at  each  interior  knot  £3  where  m3  <  A;.  Then 
by  the  above  remarks  ...,Bnk  are  in  Pk[tk,  •  •  ■  ,tn+i]-  Also  it  can  be  verified  that 
B\k,  •  •  • ,  Bnk  form  a  basis  for  the  vector  space  Pk[tk,  . . .  ,tn+i]-  Thus  any  piecewise  poly- 

n 

nomial  p(x)  in  Pk[tk,  ... ,  tn+i]  can  be  represented  uniquely  in  the  form  p(x)  =  ^  a,- Bik(x) 

i=  1 

for  tk<x<  tn+ 1.  This  representation  is  called  a  B— spline  representation  for  p(x). 
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PIECEWISE  POLYNOMIAL  INTERPOLATION 


For  n  >  k  >  1  let  ti  <  •••  <  tn+k  be  a  sequence  where  ti  <  for  t  =  1,  ..  .  ,n. 
Further  assume  that  i*  <  tk+i  and  tn  <  tn+i,  and  consider  a  set  of  n  points  {(x»,y»)  :  *  = 
1,  . .  - ,  n}  where  t*  <  <  •  •  •  <  xn  <  tn+i-  Then  we  wish  to  find  a  piecewise  polynomial 

n 

f  =  52  aiBik  defined  on  the  interval  [f*,  in+i)  which  satisfies  f{xi)  =  for  i  =  1,  . . . ,  n.  [If 

t=i 

xn  =  *n+i,  then  by  f(xn)  =  yn  we  mean  /(x„~)  =  y„.]  This  problem  has  a  unique  solution 
when  xi  <  tk+i,  U  <  Xi  <  ti+k  for  1  <  t  <  n,  and  xn  >  tn.  The  following  subroutine  is 
available  for  obtaining  the  coefficients  ax,  . ..  ,an  of  the  interpolating  piecewise  polynomial. 

CALL  BSTRP(X,  Y,  T,  n,  k,  A,  WK,  IFLAG) 

X  is  an  array  containing  x1}  ...  ,xn,  Y  an  array  containing  yls  ...  ,yn,  and  T  an  array 
containing  t\,  . . .  ,tn+k-  A  is  an  array  of  dimension  n  or  larger,  cind  IFLAG  an  integer 
variable.  On  an  initial  call  to  the  routine  the  user  may  assign  IFLAG  any  nonzero  value.  In 
this  case,  if  no  errors  are  detected  then  IFLAG  is  reset  by  the  routine  to  0  and  the  B-spline 
coefficients  a1}  ...,an  are  computed  and  stored  in  A.  The  routine  may  be  recalled  with 
IFLAG  =  0  on  input  when  only  Y  is  modified.  In  this  case,  no  error  checking  is  performed 
and  IFLAG=  0  on  output.  Also  the  B-spline  coefficients  a\,  . . . ,  an  of  the  new  interpolating 
piecewise  polynomial  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  (2k  -  l)n  or  larger  that  is  used  for  temporary  storage 
by  the  routine.  When  BSTRP  terminates,  WK  contains  information  needed  for  subsequent 
calls  to  the  routine. 

Error  Return.  IFLAG  is  assigned  the  value  1  if  a  violation  of  any  of  the  conditions 

Xl  <  <  xn 

tk<Xl<  tk+l 
ti  <  Xi  <  ti+k  for  1  <  t  <  n 
tn  Xn  <  tr»4- 1 

is  detected.  When  an  error  is  detected,  the  routine  immediately  terminates. 

Example.  Given  n  >  4  data  points  (xi,y,),  then  for  k  =  4  one  may  set  ti  =  ■  •  •  =  tk  =  xi, 
tk+i  =  xi+2  for  i  =  1,  ...,n  -  k,  and  xn  =  tn+1  =  •••  =  tn+k.  Then  z3,  ...,ir,_2  are 
the  interior  knots  for  the  interpolating  piecewise  polynomial  /.  Here  we  have  cubic  spline 
interpolation  where  the  data  points  x2  and  xn_i  are  not  knots  for  /. 

Selection  of  <  •••  <  tn+fc  given  the  data  (x»,i/j).  It  is  recommended  that  one  set 
ti  =  •  •  •  =  tk  and  t„+i  =  •  •  •  =  tn+k-  For  k  >  2  it  is  frequently  convenient  to  select 
n  —  k  points  in  x2,  . . .  ,xn_i  to  be  the  interior  knots  for  /.  (This  was  done  in  the  above 
example.)  If  k  >  2  then  an  alternative  approach,  which  often  gives  excellent  results,  is  to 
set  fjt+«  =  (xi+i  -t - 1-  Xi+k-i)/{k  -  1)  for  t  =  I,  . . . ,  n  -  k. 
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Remark.  After  the  B-spline  representation  is  obtained,  then  the  subroutine  BSPP 

can  be  used  to  obtain  the  Taylor  series  representation.  The  Taylor  series  representation  is 
what  is  normally  used  for  evaluating  piecewise  polynomials. 

Programming.  BSTRP  calls  the  subroutines  BSPEV,  BANFAC,  and  BANSLV.  BSTRP 
is  a  modified  version  by  A.  H.  Morris  of  the  subroutine  SPLINT.  The  routines  SPLINT, 
BANFAC,  and  BANSLV  were  written  by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Verlag,  1978. 
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CONVERSION  OF  PIECEWISE  POLYNOMIALS  FROM 
B-SPLINE  TO  TAYLOR  SERIES  FORM 

For  n  >  k  >  1  let  <  tn+k  be  a  sequence  where  U  <  ti+i  for  i  =  1, 

Further  assume  that  tk  <  tn+1  and  let  f{x)  =  £  a;Bifc(x )  for  tk  <  x  <  tn+1.  If  &  <  •  •  ■  < 

»=i 

&+i  are  the  distinct  points  in  the  sequence  {tk,  . . .  ,t„+1}  then  the  piecewise  polynomial  / 

k 

can  be  represented  in  the  form  f(x)  =  £  c,y(x  -  ^y)’-1  for  <  x  <  fy+1  (j  -1, 

«=i 

The  following  subroutine  is  available  for  obtaining  the  coefficients  c,y  of  this  representation. 

CALL  BSPP(T,  A,  n,  k,  BREAK,  C,  L,  WK) 

T  is  an  array  containing  t1}  ,  tn+k  and  A  an  array  containing  ai,  ... ,  an.  BREAK 

is  an  array  of  dimension  £  +  1  or  larger,  C  a  2-dimensional  array  of  dimension  k  x  £,  and 
L  a  variable.  When  BSPP  is  called  then  L  is  assigned  the  value  £  (which  is  computed  by 
the  routine),  the  break  points  ^  are  found  and  stored  in  BREAK,  and  the 

coefficients  c»y  are  computed  and  stored  in  C.  The  jth  column  of  the  matrix  C  then  contains 
the  coefficients  of  the  jth  polynomial  forming  f  (j  —  1,  ...  ,£). 

WK  is  an  array  of  dimension  k(k  +  1)  or  larger  that  is  used  for  work  space  by  the 
routine. 

Remarks. 

(1)  Since  £<n-k  +  1,  BREAK  may  be  declared  to  be  of  dimension  n  -  k  +  2  and  C  to 
be  of  dimension  k  x  (n  —  k  +  1). 

(2)  After  C  is  obtained,  then  PPVAL  may  be  used  to  evaluate  /  at  any  point  x. 

Programming.  BSPP  is  a  reformulation  by  A.  H.  Morris  of  the  subroutine  BSPLPP,  written 
by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Verlag,  1978. 
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PIECEWISE  POLYNOMIAL  EVALUATION 


k 

Given  Xi  <  •  •  •  <  X£+1.  If  /  is  a  piecewise  polynomial  where  /(x)  =  ^  c,-y(x  —  xy)’-1 

<=i 

for  Xj  <  x  <  Xj+i  [j  =  1,  ...,£),  then  the  following  subroutine  is  available  for  computing 
/  at  any  point  x. 

CALL  PP VALpf,  C,  k,  £,  XI, YI,  m) 

X  is  an  array  containing  the  knots  x\t  and  C  a  k  x  l  matrix  containing  the 

coefficients  cty.  It  is  assumed  that  k  >  1  and  £  >  1.  Let  xi,  . .  .,zm  be  the  points  at  which 
/  is  to  be  evaluated.  XI  is  an  array  containing  xi,  ... ,  xm  and  YI  an  array  of  dimension  m 
or  larger.  When  PPVAL  is  called,  /(xy)  is  computed  and  stored  in  YI(j)  for  j  =  1,  . ..  ,m. 

Remarks. 

(1)  X  need  not  contain  the  knot  s*+i. 

(2)  It  is  not  required  that  /  be  continuous  at  an  interior  knot  xt-.  If  n  appears  in  XI  then 
f(xi+)  is  computed. 

(3)  It  is  not  required  that  the  output  points  xy  in  XI  be  in  the  interval  [xi,  xt+1).  If  xy  <  xx 
then  S,Cii(x  —  xi),_1  is  evaluated  at  xy.  Otherwise,  if  xy  >  xi+ 1  then  S^cti(x  —  x^)*-1 
is  evaluated  at  xy. 

Programming.  PPVAL  is  an  adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones 
(Sandia  Laboratories). 
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WEIGHTED  LEAST  SQUARES  PIECEWISE  POLYNOMIAL  FITTING 


For  n  >  k  >  1  let  ti  <  •  ••  <  in+fc  be  a  sequence  where  t*  <  t,-+fc  for  t  =  1,  . . .  ,n. 
Further  assume  that  tk  <  tk+i  and  tn  <  tn+i,  and  consider  a  set  of  points  {(x,-,^)  :  i  = 
1,  . . . ,  m}  where  it  <  xi  <  ■  •  •  <  xm  <  tn+i-  Let  Wi  >  0  («'  =  1,  . . .  ,m)  be  weights.  Then 

n 

the  subroutine  BSL2  is  available  for  finding  a  piecewise  polynomial  /  =  Y2aiBik  defined 

m  i=  1 

on  the  interval  which  minimizes  ~  Vi)2-1 

i=i 

CALL  BS L2(T,  n,k,X,  Y,  WGT,  m,A,  WK,Q,  IERR) 

T  is  an  array  containing  t\>  . . . ,  tn+k,  X  an  array  containing  xi,  . . . ,  xm,  Y  an  array 
containing  y\,  ,  ym,  and  WGT  an  array  containing  tni,  . . . ,  wm.  A  is  an  array  of  dimension 

n  or  larger,  and  IERR  an  integer  variable.  When  BSL2  is  called,  if  no  input  errors  are 
detected  then  IERR  is  set  to  0  and  the  B-spline  coefficients  a*,  ...  ,an  of  the  least  squares 
approximation  /  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  n  or  larger,  and  Q  an  array  of  dimension  kn  or  larger. 
WK  and  Q  are  work  spaces  for  the  routine. 

Error  Return.  IERR  is  assigned  the  value  1  if  any  of  the  conditions 

n  >  k  >  1 
tn  <  in+1 

tk<X  !<•■*<  <  *n+l 

is  violated.  When  an  error  is  detected,  the  routine  immediately  terminates 

Selection  of  <  ••■  <  tn+k  given  the  data  It  is  recommended  that  the  knots  tu 

be  selected  so  that  there  are  data  points  x;t  <  ••  •  <  xtn  satisfying 

tk  <  2^!  < 

*i/  <  xiu  <  tv+k  for  v  =  2,  . . .  ,n. 

If  these  conditions  are  satisfied  then  the  least  squares  approximation  is  unique. 

Remark.  After  the  B-spline  representation  Eia,-Rt-fc  of  the  least  squares  approximation  is 
obtained,  then  the  subroutine  BSPP  can  be  used  to  obtain  the  Taylor  series  representation. 
The  Taylor  series  representation  is  normally  used  for  evaluating  piecewise  polynomials. 

Programming.  BSL2  calls  the  subroutines  BSPEV,  BCHFAC,  and  BCHSLV.  BSL2  is  a 
modified  version  by  A.  H.  Morris  of  the  subroutine  L2APPR.  L2APPR,  BCHFAC,  and 
BCHSLV  were  written  by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Verlag,  1978. 


1If  n  =  tn+i  then  by  /(s;)  we  mean  /(z,  — ). 
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BI-SPLINES  UNDER  TENSION 

Given  a  tension  factor  a  and  a  set  X  =  {zi,  . . . ,xm}  where  *!<•■•<  xm.  Let  Sff(X) 
denote  the  collection  of  splines  having  tension  a  and  the  knots  xx,  Then  S^X) 

is  a  vector  space.  Also  each  spline  /  (z)  in  Sa  (X)  is  uniquely  characterized  by  the  values 
f(x  1),  ••.,/( i»)  and  the  slopes  /'pi)  and  f'(xm).  Let  tfc(z)  (*  =  1,  ...,m)  denote  the 
spline  in  5a(X)  satisfying 

Mx*)  =  1 

t^i(zjt)  =  0  for  k  ^  t 
^ilx  l)  =  $(®m)  =  0 

and  let  ^m+ i,ipm+2  be  the  splines  satisfying 

ipm+i{xi)  =  0  t pm+2{xi)  =  0  (»'  =  1,  . . . , m) 

<Am+l(si)  =  l  'P'm+2(xl)  =  0 

V’m+l(Xm)  =  ®  i)  = 

m 

Then  . . . ,  tpm+2  }  is  a  basis  for  S„  (X)  and /=£  /(*,•)&+ f,{x1)ipm+1  +  f{xm)^m+2 

i=l 

for  each  spline  /(z)  in  Str(X). 

Let  Y  —  {j/i ,  . . . ,  yn}  where  yi  <  *  •  •  <  yn  and  let  {ipx ,  . . . ,  ipn+2  }  be  the  corresponding 
basis  for  Sa(Y).  Then  we  note  that  there  exists  an  unique  surface 

m+2  n+2 

Fix,y)  =  53  S  a«i^«(x)V'y(y) 

i=l  j=  i 

in  the  tensor  product  space  5CT(X)  ®  Sa(Y)  which  satisfies  the  conditions 

F(xi>yj)  =  /(*i>y;)  *  =  1,  ...,m  j  =  l,...,n 

D2F(xi,  yi)  =  D2/(z«,yi)  1 

?  i  =  1,  ....  m 

u\  D2F(xi,yn)  =  D2f{Xi,yn)  J 

D\F{xl,yj)  =  Dlf{xuyj)  j  ^ 

DxF(xm,yi)  =  D1f{xm,yj))  3 
DiD2F(xk,yt)  =  DiD2f(xk,yi)  k  =  l,m  1=1, n 

for  given  data  /(z^yy),  D2f(xi,y1),  . . . ,  DxD2f{xk,  y*).1  Such  a  surface  is  called  a  6*- 
spline  with  tension  a.  It  is  easily  checked  that  the  bi-spline  F(x,  y)  has  the  following 
properties: 

(1)  F(x,y)  is  a  C2  mapping  on  [zi,zm]  x  [yi,y„]. 

(2)  The  partial  derivatives  D\D\F{x,  y)  and  D\D\F{x,y)  exist  and  are  continuous,  and 
D\DlF{x,y)  =  DlD\F{x,y). 

(3)  For  each  fixed  y  the  mapping  z  F{x,  y)  is  a  spline  in  SV(X),  and  for  each  fixed  z 
the  mapping  y  >->  F(x,  y)  is  a  spline  in  Sa  (Y). 

1DXF  and  D?F  denote  the  partial  derivatives  of  F. 
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For  a  given  tension  factor  a,  let  Fa  denote  the  unique  bi-spline  in  Sa (X)  ®  S^fy) 
which  satisfies  conditions  (*).  If  a  =  0  then  Fa  is  the  standard  bicubic  spline.  Also  it  can 
be  verified  that  when  a  —>  oo,  Fa  converges  uniformly  on  [zi,  xm\  x  [yi,  yn]  to  the  piecewise 
bilinear  function  £(z,  y)  where 


\ _ ft  \  xi+i  x  yy+i  y  <  tr  \  x*+i  x  y  yy 

£{x>  y)  —  f{xi>  yy)  j,  .  +  f{xi,yj+i) 


+  f{xi+i>yj) 


vj  kj 


x-Xj  Vj+1  -  y 


+  fixi+i,yj+i) 


x~xi  y  -  y j 


hi  kj  hi  kj 

for  Xi  <  x  <  zt+i  and  y y  <  y  <  yy+i-  Here  hi  =  xi+i  -  z,-  and  kj  =  yy+i  -  yy. 
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BI-SPLINE  UNDER  TENSION  SURFACE  INTERPOLATION 


Given  Xi  <  •  •  •  <  xm  and  yi  <  ■  •  •  <  yn.  Also  assume  that  we  are  given  the  values 
z<3  (*  =  !»  ,m;  j  =  1,  ...,n)  and  a  tension  factor  a.  Then  the  subroutine  SURF  is 

available  for  finding  a  bi-spline  F(x,y)  with  tension  a  that  satisfies  F(x,-,yy)  =  z^j  for  each 
i,j.  Boundary  conditions  can  be  imposed  on  the  surface  F{x,y)  if  desired. 

CALL  SURF(m, n, X,  Y,  Z,  kz, OPT, DDZ,  WK, <r, IERR) 

X  is  an  array  containing  xx,  ...,xm,Y  an  array  containing  yi,  ...  ,yn,  and  Z  the  mx  n 
matrix  (z,-y) .  The  argument  kz  is  the  number  of  rows  in  the  dimension  statement  for  Z  in 
the  calling  program.  It  is  assumed  that  m  >  2,  n  >  2,  and  kz  >  m. 

OPT  is  an  array,  called  the  option  vector,  which  permits  the  user  to  specify  any 
boundary  conditions  that  are  to  be  imposed  on  the  surface.  If  no  boundary  conditions 
are  to  be  specified  then  OPT  may  be  declared  to  be  of  dimension  1  and  OPT(l)  must  be 
assigned  the  value  0.  The  details  concerning  the  specification  of  boundary  conditions  in 
OPT  are  given  below. 

DDZ  is  a  3-dimensional  array  of  dimension  m  x  n  x  3  and  IERR  is  a  variable.  When 
SURF  is  called,  if  no  input  errors  are  detected  then  IERR  is  assigned  the  value  0  and  the 
partial  derivatives  DlF{xi,yj),DlF{xi,yj),D\DlF{xi,yj)  .(»  =  1,  =  1,  ...,n) 

are  computed  and  stored  inJDDZ.  DDZ(t,j,l)  =  D\F{xi,yj),  DDZ(j,j,2)  =  D\F{xi,yj), 
and  DDZ(t,y,3)  =  D\D\F{xi,  yy)  for  eadi  i,j. 

WK  is  an  array  of  dimension  m  +  2n  or  larger  that  is  used  for  a  work  space. 

Error  Return.  IERR  reports  the  following  input  errors: 

IERR  =  1  if  m  <  2  or  n  <  2. 

IERR  =2  if  si  <  •  •  •  <  xm  or  yi  <  •  •  •  <  yn  is  not  satisfied. 

IERR  =  3  if  OPT  contains  an  error. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remark.  After  DDZ  is  obtained  then  SURF2  and  NSURF2  may  be  used  to  evaluate  the 
bi-spline  F(x,y). 

The  option  vector  OPT.  If  no  boundary  conditions  are  to  be  imposed  then  OPT  may  be 
declared  to  be  of  dimension  1  and  OPT(l)  must  have  the  value  0.  Otherwise,  OPT  is  an 
array  containing  the  information  keyi,  datai,  key2,  data2,  ...,  key,,  data,,  0.  The  last 
entry  in  OPT  is  the  value  0.  Each  group  of  data  key,-,  data,-  (»  =  1,  . . . ,  s)  is  called  an 
option.  Each  key^  is  an  integer  and  data*  is  a  list  of  partial  derivative  values  that  the 
surface  F(x,y)  is  required  to  satisfy.  The  following  options  are  available: 
key  =  1  The  values  D\F{xi,yj)  [j  =  1,  .. .  ,n)  must  be  satisfied, 
key  =  2  The  values  DiF(xm,yJ)  (j  =  1,  ...,n)  must  be  satisfied, 
key  =  3  The  values  D2F(x,-,  y i)  (»  =  1,  .. .  ,m)  must  be  satisfied, 
key  =  4  The  values  D2F(x,-,  y„)  (*  =  1,  . . . ,  m)  must  be  satisfied. 
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key  =  5  The  value  DiD3F(xi,yi)  must  be  satisfied, 
key  =  6  The  value  DiD2F{xm,  yj)  must  be  satisfied, 
key  =  7  The  value  D\D2F[xi,yn)  must  be  satisfied, 
key  =  8  The  value  DiD2F(xm,  yn)  must  be  satisfied. 

The  order  of  the  options  in  OPT  is  arbitrary.  If  an  unrecognized  key  is  used  then  the  error 
indicator  IERR  is  assigned  the  value  3  and  the  routine  terminates. 

Example.  Assume  that  we  have  an  array  DY1  containing  values  D2F(xi,yi)  (t  =  1,  . . .  ,m) 
which  are  to  be  satisfied,  and  that  we  also  want  DiDiF(xm,yn)  =  —1.3  to  be  satisfied. 
Then  OPT  must  be  of  dimension  >  m  +  4  and  OPT  can  be  defined  as  follows: 

OPT(l)  =  3.0  (First  option) 

DO  10  I  =  1,M 
10  OPT  (I  +  1)  =  DY1(I) 

OPT  (M  +  2)  =  8.0  (Second  option) 

OPT  (M  +  3)  =  -1.3 

OPT  (M  +  4)  =  0.0  (Terminates  the  option  vector) 

Background.  The  evaluation  of  D\ F(xi,  yj),  D\F{xi,  yy),  and  D\D\F(xj,yj)  reduce  to  the 
evaluation  of  second  derivatives  of  splines.  Specifically,  for  each  i  <  m  D\F{xi,  yi),  ..., 
D\F(xi,yn)  are  the  second  derivatives  that  characterize  the  spline  y  i— »  F(xj,  y),  and  for 
each  j  <  n  D\F(xi,yj ),  . . . ,  D\F{xm,yj)  are  the  second  derivatives  that  characterize  the 
spline  x  i-+  F(x,  yj).  Also  D\D\F{x\,yj)  and  DiD%F(xm,  yj)  (j  —  1,  ...  ,n)  are  the  second 
derivatives  that  characterize  the  splines  y  DiF{xi,y)  and  y  i-*  DiF(xm,y).  For  each 
j  <  m,  after  one  obtains  the  values  D\F{xi,  yj)  through  which  the  spline  x  i— »  D\F{x,yj) 
will  pass  and  the  end  slopes  DiD\F{x\,yj)  and  D\D\F{xm,yj)  which  this  spline  must  have, 
then  the  second  derivatives  that  characterize  this  spline  can  be  computed.  D\D\F{x\,yj), 
. . .  ,D\D\F{xm,yj)  are  the  second  derivatives  that  characterize  x  i— *•  D\F{x,yj). 

Programming.  SURF  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  SURF  was 
written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin),  and  modified  by 
A.  H.  Morris. 
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BI-SPLINE  UNDER  TENSION  EVALUATION 

Given  xx  <  •  •  *  <  xm  and  yx  <  •  •  •  <  y„,  and  let  F(x,  y)  be  a  bi-spline  with  tension  a.  If 
the  partial  derivatives  D\F(xi,yj), D\F{xi,yj),  D\D\F{xi,yj)  are  known  for  *  =  1,  , . .  ,m 
and  j  =  1,  . . .  ,n,  then  the  function  SURF2  may  be  used  for  evaluating  F(x,  y)  at  a  single 
point,  and  the  subroutine  NSURF2  may  be  used  for  evaluating  F(x,y)  on  a  grid  of  points. 

SURF2(s,  t,  m,  n,  X,  Y,  Z,  kz,  DDZ,  a) 

X  is  an  array  containing  xx,  ...,xm,  Y  an  array  containing  yx,  . ..,yn,  and  Z  an 
m  X  n  matrix  containing  the  values  F(z,-,yJ).  The  argument  kz  is  the  number  of  rows  in 
the  dimension  statement  for  Z  in  the  calling  program.  It  is  assumed  that  m  >  2,  n  >  2, 
and  kz  >  m. 

DDZ  is  a  3-dimensional  array  of  dimension  m  x  n  x  3  containing  the  partial  derivatives 
where 

DDZ(t,j,  1)  =  D\F{xi,yj) 

DDZ(t,i,2)  =  D?F’(xi,yy) 

DDZ(t-,j,3)  =  D?D|F(:r<,yJ) 

for  each  i,j.  SURF2(s,t,  m,  n,X,Y,  Z,  kz,  DDZ,  o')  =  F(s,t)  for  any  point  ( s,t ). 

Remark.  After  DDZ  has  been  obtained,  SURF2  may  be  repeatedly  called  to  evaluate  the 
surface  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However,  if  a  is 
modified  then  the  derivative  information  in  DDZ  will  have  to  be  recomputed  before  SURF2 
can  be  used  with  the  new  tension  factor. 

Programming.  SURF2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  SURF2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 

CALL  NSU RF2(smin, smax, £min? ^max> j ktu, to, n, 

X ,  Y,  Z ,  kz,  DDZ, WORK,  a) 

The  arguments  smin  and  smax  are  the  lower  and  upper  limits  of  the  x-coordinates  of 
the  grid  on  which  F(x,  y )  is  to  be  evaluated,  and  the  arguments  tm;n  and  imax  are  the  lower 
and  upper  limits  of  the  y-coordinates.  The  purpose  of  the  routine  is  to  evaluate  the  surface 
at  the  points  where 

=  Smin  "b  (*" 

—  ^rain  "h  (j 

for  »  =  1,  . . . ,  ms  and  j  =  1,  . . . ,  «t-  It  is  assumed  that  ma  >  1  and  nt  >  1. 

W  is  a  2-dimensional  array  of  dimension  kw  x  nt  where  kw  >  ms.  When  NSURF2  is 
called  W(t,j)  is  assigned  the  value  F(sj,£y)  for  »  =  1,  .. .  ,ms  and  j  =  1,  ...  ,nt. 


-1) 

-1) 


smax 

TOa  —  1 
^max  —  ^mi 

nt  ~  1 
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The  arguments  m,  n,  X,  Y,  Z,  kz,  DDZ,  a  are  the  same  as  in  SURF2.  WORK  is  an  array 
of  dimension  4 m3  or  larger  that  is  used  for  a  work  space. 

Programming.  NSURF2  employs  the  subroutine  SNHCSH.  NSURF2  was  written  by 
A.  K.  Cline  (University  of  Texas  at  Austin). 
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SURFACE  INTERPOLATION  FOR  ARBITRARILY  POSITIONED 

DATA  POINTS 


Let  {(if,  y», Zi)  :  »  =  1,  . . . ,  n}  be  a  set  of  4  or  more  points  which  are  not  collinear.  If 
(xj, t/,)  ^  (ij,yy)  for  t  ^  j  then  the  problem  is  to  find  a  smooth  mapping  z  =  F(x,y)  for 
which  Zi  =  F(x{,  yi)  for  t  =  1,  ... ,  n.  The  desired  degree  of  smoothness  might  vary,  but  it 
is  almost  always  required  that  F(x,y)  be  at  least  continuously  differentiable. 

A  procedure  for  constructing  a  smooth  mapping  F(x,  y)  generally  contains  the  following 
components: 

(1)  An  algorithm  for  forming  a  triangular  grid  for  the  convex  hull  of  {(if,yf)  :  i  = 
1,  . . .  ,n}.  The  data  points  (x,-,  y,)  are  the  vertices  of  the  triangular  cells  of  the  grid. 

(2)  A  procedure  for  estimating  the  first  (and  possibly  higher  order)  partial  derivatives 
of  F(x,  y)  at  the  data  points  (x*,yf).  There  is  currently  no  known  best  method  for 
performing  this  task.  At  a  point  (i*,yf),  it  is  agreed  that  the  derivative  estimation 
should  depend  not  only  on  but  also  on  Zj  for  neighboring  points  (i y,yy).  However, 
the  number  of  neighboring  points  that  should  be  used  in  the  derivative  estimation  is 
normally  unclear. 

(3)  For  any  point  (i,  y)  in  the  grid,  a  routine  for  finding  the  triangular  cell  which  contains 
the  point.  If  extrapolation  is  to  be  permitted,  then  the  region  outside  of  the  grid  must 
be  partitioned  and  a  routine  provided  for  locating  any  point  which  lies  outside  the  grid. 

(4)  A  smooth  interpolating  algorithm  for  evaluating  F(x,  y)  on  each  triangular  cell  of  the 
grid.  If  extrapolation  is  to  be  permitted,  then  an  algorithm  must  also  be  provided  to 
compute  F( x,  y )  on  each  cell  of  the  partitioned  region  outside  of  the  grid. 

Generally,  the  derivative  estimation  appears  to  be  the  most  ad  hoc  portion  of  most  smooth 
interpolating  procedures.  This  quite  probably  is  unavoidable  at  the  present  time.  However, 
it  is  unfortunate  since  the  manner  in  which  the  derivative  estimation  is  performed  can 
significantly  affect  the  results  obtained  from  any  interpolating  procedure. 

The  subroutines  BVEP  and  BVIP2  are  available  for  obtaining  a  continuously  differ¬ 
entiable  surface  z  =  F(x,y)  for  which  z»  =  F(x,-, y,)  for  i  =  1,  Extrapolation  is 

allowed,  and  the  user  is  permitted  to  specify  (via  the  argument  nc)  the  number  of  neighbor¬ 
ing  points  to  be  used  for  derivative  estimation.  BVIP  is  used  if  _F(*,y)  is  to  be  evaluated 
on  an  arbitrary  collection  of  output  points,  whereas  BVIP2  is  applicable  only  if  F(x,  y)  is 
to  be  evaluated  on  a  rectangular  grid  of  output  points.  If  BVIP  is  employed  to  evaluate 
F(x,y)  on  a  rectangular  grid,  then  BVIP  will  produce  the  same  results  as  BVIP2  but  it 
will  be  less  efficient. 

CALL  BVIP(MO,  nc,  n,  X,  Y,  Z,  m, XI,YI,ZI,IWK,WK,IERR) 

A  is  an  array  containing  x\ ,  . . . ,  xn ,  Y  an  array  containing  yx ,  . . . ,  yn ,  and  Z  an  array 
containing  Z\t  ...  ,zn.  The  input  argument  nc  is  the  number  of  neighboring  points  to  be 
used  for  derivative  estimation.  It  is  assumed  that  2  <  nc  <  n  and  nc  <  25.  Currently 
no  theory  is  available  for  indicating  how  nc  should  be  set.  The  only  comment  that  can  be 
made  is  that  setting  nc  to  3,4,  or  5  normally  produces  satisfactory  results. 
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It  is  assumed  that  F(x,y)  is  to  be  evaluated  at  the  points  (xi,yi),  XI 

is  an  array  containing  xl}  . . . ,  xm,  YI  an  array  containing  yi,  . . .  ,ym,  and  ZI  an  array  of 
dimension  m  or  larger.  When  BVIP  is  called,  if  no  input  errors  are  detected  then  F  (x» ,  yt) 
is  computed  and  stored  in  ZI(t)  for  i  =  1,  ...  ,m. 

One  may  wish  to  recall  BVIP  a  number  of  times  to  compute  F(x,y)  for  different  sets 
of  points.  If  recalls  are  needed  then  a  portion  of  the  information  that  is  generated  on  the 
first  call  to  BVIP  can  frequently  be  reused.  The  reuse  of  information  is  controlled  by  the 
input  argument  MO.  MO  must  have  the  value  1  on  the  first  call  to  BVIP.  For  subsequent 
calls  MO  may  be  assigned  the  following  values: 

MO  =  1  This  setting  must  be  employed  when  any  of  the  data  nc,n,X,Y 
is  modified.  In  this  case,  none  of  the  previously  generated  infor¬ 
mation  can  be  reused. 

MO  =  2  This  setting  may  be  used  when  nc,n,X,  Y  are  not  modified. 

MO  =  3  This  setting  is  permissible  when  only  Z  is  modified. 

If  MO  ^  1  then  the  contents  of  IWK  and  WK  must  not  be  altered. 

IWK  is  an  array  of  dimension  Am  -f-  m  or  larger  where  k  =  max{31, 27  +  nc},  and  WK 
is  an  array  of  dimension  8n  or  larger.  IWK  and  WK  are  storage  areas  for  the  routine. 

Error  Return.  IERR  is  an  integer  variable.  If  no  errors  are  detected  then  IERR  is  set  to  0. 
Otherwise,  IERR  is  assigned  one  of  the  following  values: 

IERR  =  1  MO  is  not  1,  2,  or  3. 

IERR  =  2  Either  2  <  ne  <  n  or  nc  <  25  is  violated. 

IERR  =  3  n  <  4 
IERR  =  4  m  <  1 

IERR  —  5  Either  nc  or  n  has  been  modified.  This  cannot  occur  if  MO  ±  1. 

IERR  =  6  The  argument  m  has  been  modified.  This  cannot  occur  if  MO=  3. 

IERR  =  7  Points  (x*,yi)  and  (xy,yy)  are  equal  or  too  close  where  IWK(l)  = 
i  and  IWK(2)  =  j. 

IERR  =  8  The  points  (x,-,  y,-,  Zi)  (i  =  1,  . . . ,  n)  are  collinear  or  almost  collinear. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks. 

(1)  The  procedure  is  invariant  under  a  rotation  of  the  x-y  coordinate  system. 

(2)  The  results  are  exact  when  F(x,  y)  represents  a  plane. 

(3)  Derivative  estimation  at  a  data  point  depends  on  points  closest  to  the  data  point.  Thus 
the  procedure  is  dependent  on  the  scaling  of  the  abscissae  x,-  and  ordinates  y*  of  the 
data  points. 

Programming.  BVIP  employs  the  subroutines  IDTANG,  IDCLDP,  IDLCTN,  IDPDRV, 
IDPTIP  and  the  function  IDXCHG.  The  routines  save  and  exchange  information  in  labeled 
common  blocks.  The  block  names  are  IDLC  and  IDPI.  The  routines  were  written  by 
Hiroshi  Akima  (Institute  for  Telecommunication  Sciences,  Boulder,  Colorado).  IDPTIP  was 
modified  by  Albrecht  Preusser  (Fritz-Haber-Institut  der  Max-Planck-Gesellschaft,  Berlin). 
The  error  handling  was  modified  by  A.  H.  Morris. 
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CALL  BVIP2(MO,  nc,  n, X,  Y,  Z,l,  m,  XI,YI,ZI,IWK,WK,IERR) 

X  is  an  array  containing  x\,  . ..,  xn,  Y  an  array  containing  yi,  . . .  ,yn,  and  Z  an  array 
containing  zi,  ...  ,zn.  The  input  argument  nc  is  the  number  of  neighboring  points  to  be 
used  for  derivative  estimation.  It  is  assumed  that  2  <  nc  <  n  and  nc  <  25.  Currently 
no  theory  is  available  for  indicating  how  nc  should  be  set.  The  only  comment  that  can  be 
made  is  that  setting  nc  to  3,  4,  or  5  normally  produces  satisfactory  results. 

It  is  assumed  that  F(x,  y)  is  to  be  evaluated  at  (ii,yy)  for  *  =  1  ,...,£  and  j  = 
1,  . . . ,  m.  XI  is  an  array  containing  xi ,  . . . ,  it,  YI  an  array  containing  fa,  ...,  ym ,  and  ZI 
a  2-dimensional  array  of  dimension  l  x  m.  When  BVIP2  is  called,  if  no  input  errors  are 
detected  then  F(i,,  yy)  is  computed  and  stored  in  ZI(»,  j)  for  t  =  1,  . . . ,  t  and  j  —  1,  ...  ,m. 

One  may  wish  to  recall  BVIP2  a  number  of  times  for  different  grids  (i,-,yy).  If  results 
are  needed  then  a  portion  of  the  information  that  is  generated  on  the  first  call  to  BVIP2 
can  frequently  be  reused.  The  reuse  of  information  is  controlled  by  the  input  argument 
MO.  MO  must  have  the  value  1  on  the  first  call  to  BVIP2.  For  subsequent  calls  MO  may 
be  assigned  the  following  values: 

MO  =  1  This  setting  must  be  employed  when  any  of  the  data  nc,  n,X,Y 
is  modified.  In  this  case,  none  of  the  previously  generated  infor¬ 
mation  can  be  reused. 

MO  =  2  This  setting  may  be  used  when  nc,n,X,Y  are  not  modified. 

MO  =  3  This  setting  is  permissible  when  only  Z  is  modified. 

If  MO  7^  1  then  the  contents  of  IWK  and  WK  must  not  be  altered. 

IWK  is  an  array  of  dimension  kn  +  tm  or  larger  when  k  =  max{31, 27  +  nj,  and  WK 
is  an  array  of  dimension  5n  or  larger.  IWK  and  WK  are  storage  areas  for  the  routine. 

Error  Return.  IERR  is  an  integer  variable.  If  no  errors  are  detected  then  IERR  is  set  to 
0.  Otherwise,  IERR  is  assigned  one  of  the  following  values: 

IERR  =  1  MO  is  not  1,  2,  or  3. 

IERR  =  2  Either  2  <  nc  <  n  or  nc  <  25  is  violated. 

IERR  =  3  n  <  4. 

IERR  =  4  Either  i  <  1  or  m  <  1. 

IERR  =  5  Either  nc  or  n  has  been  modified.  This  cannot  occur  if  MO  ^  1. 

IERR  =  6  Either  form  has  been  modified.  This  cannot  occur  if  MO  =  3. 

IERR  =  7  Points  (ar»,yt)  and  (zy,y y)  are  equal  or  too  close  where  IWK(l)=t 
and  IWK(2)  =  j. 

IERR  =  8  The  points  (i;,  y,-,  z^)  n)  are  collinear  or  almost  collinear. 


439 


When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks. 

(1)  The  procedure  is  invariant  under  a  rotation  of  the  x-y  coordinate  system. 

(2)  The  results  are  exact  when  F(x,y)  represents  a  plane. 

(3)  Derivative  estimation  at  a  data  point  depends  on  points  closest  to  the  data  point.  Thus 
the  procedure  is  dependent  on  the  scaling  of  the  abscissae  z*  and  ordinates  y j. 

Programming.  BVIP2  employs  the  subroutines  IDTANG,  IDCLDP,  IDGRID,  IDPDRV, 
IDPTIP  and  the  function  IDXCHG.  The  routines  save  and  exchange  information  in  a  lar 
beled  common  block  named  IDPI.  The  routines  were  written  by  Hiroshi  Akima  (Institute 
for  Telecommunication  Sciences,  Boulder,  Colorado).  IDPTIP  was  modified  by  Albrecht 
Preusser  (Fritz-Haber-Institut  der  Max-Planck-Gesellschaft,  Berlin).  The  error  handling 
was  modified  by  A.  H.  Morris. 

References. 

(1)  Akima,  Hiroshi,  “A  Method  of  Bivariate  Interpolation  and  Smooth  Surface  Fitting  for 
Irregularly  Distributed  Data  Points,”  ACM  Trans.  Math  Software  4  (1978), pp.  148- 
159. 

(2)  Preusser,  A.,  “Remark  on  Algorithm  526,”  ACM  Trans.  Math  Software  11  (1985), 
pp.  186-187. 
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WEIGHTED  LEAST  SQUARES  FITTING  WITH  POLYNOMIALS 

OF  N  VARIABLES 

Let  {(xx^\  ...,xi’^)  :  i  =  1,  ...,£}  be  a  set  of  £  distinct  points,  zx,  be  the 

corresponding  function  values  to  be  approximated,  and  wx,  . . . ,  uy  be  positive  weights. 
Then  for  any  nonnegative  integer  IDEG  where  (n+I^EG)  <  l,1  the  subroutines  MFIT  and 
DMFIT  are  available  for  obtaining  the  coefficients  of  the  unique  polynomial  F(x x,  . . .  ,x„) 

of  degree  IDEG  which  minimizes  w*[F(xi'\  . —  z,-]2.  Also,  the  subroutines 

i=i 

MEVAL  and  DMEVAL  are  available  for  computing  this  polynomial.  MFIT  and  MEVAL 
yield  single  precision  results,  and  DMFIT  and  DMEVAL  yield  double  precision  results. 

CALL  MFIT(n,  IDEG,  m,  £,  X,  kx,  Z,  W,  R,  IER,IWK,WK,LIWK,LWK, 

MIWK,MWK) 

CALL  D M FIT(n, IDEG , m, £, X, kx,  Z, W,R, IER,IWK,WK,LIWK,LWK, 

MIWK,MWK) 

It  is  assumed  that  n  >  1  and  £  >  1.  X  is  an  £  X  n  matrix  whose  ith  row  contains  the 
point  (x}'\  . . . ,  xi’5);  i.e.,  X(i,j)  =  xj^  for  t  =  1,  . . .  ,£  and  j  =1,  ...  ,n.  The  argument 
kx  is  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program.  Z  is  an 
array  containing  Zx,  ...  ,zt  and  W  an  array  containing  tox,  . . . ,t Vf  X  and  Z  are  modified 
by  the  routine. 

Remark.  For  IDEG  >  0,  («+!DEGj  polynomials  l^x,  .. . ,  xn,xx,  xxx2f  ...  are  needed  for 
a  basis  of  the  space  of  polynomials  of  degree  <  IDEG.  The  basis  polynomials  are  ordered. 
For  k  >  1,  the  degree  k  —  1  basis  polynomials  precede  the  degree  k  polynomials.  The 
degree  k  basis  polynomials  are  Xix  •••x,i  where  1  <  i'x  <  •  <  ik  <  n.  For  any  two  such 

polynomials  x^  •  •  •  Xik  and  x3l  •  •  ■  x3k,  let  r  be  the  smallest  integer  such  that  *r  ^  jT.  Then 
I,-,  •••Xi k  precedes  x3l  •  •  •  x3k  when  iT  <  jT. 

IDEG  and  m  are  variables.  If  IDEG  >  0  then  the  routine  attempts  to  obtain  the 
polynomial  F(xx,  . . .  ,x„)  of  degree  IDEG  which  is  the  best  least  squares  fit.  Otherwise,  if 
IDEG  <  0  then  it  is  assumed  that  m  >  1  and  that  the  first  m  basis  polynomials  are  to  be 
used  to  obtain  the  least  squares  fit.  When  the  routine  terminates,  IDEG  =  the  degree  of 
the  polynomial  F(x x,  . . . ,  xn)  obtained  and  m  =  the  number  of  basis  polynomials  that  are 
actually  used. 

R  is  an  array  of  dimension  £  or  larger.  R(  t)  =  zt-  -  F(x}'\  ...,  for  :  =  1,  . . .  ,£ 
when  the  routine  terminates. 

IWK  is  an  array  of  dimension  LIWK  and  WK  an  array  of  dimension  LWK.  When 
the  routine  terminates,  IWK  and  WK  contain  the  information  needed  for  computing  the 
polynomial  F(xx,  . .. ,x„ ).  Sufficient  storage  for  IWK  and  WK  can  be  assured  by  setting 
LIWK  and  LWK  as  follows:  If  IDEG  >  0  then  let  N  —  min{£,  (n+I°EG)}  and  S  =  IDEG. 

1  (o)  =  1  and  (?)=  for  i=l,2,... 
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Otherwise,  if  IDEG  <  0  then  let  N  =  m  and  6  be  the  smallest  nonnegative  integer  such 
that  ("+*).>  m.  Then  set 

LIWK  >4 N  +  8n 

LWK>2N  +  n  +  l  +  tN+l(N-l){N-2). 

N  is  the  maximum  number  of  basis  polynomials  that  will  be  used,  and  S  is  the  degree  of 
the  polynomial  F(x i,  . . . ,  xn)  if  N  basis  polynomials  are  used. 

MIWK  and  MWK  are  variables.  MIWK  is  set  by  the  routine  to  the  dimension  needed 
for  IWK,  and  MWK  is  set  to  the  dimension  needed  for  WK.  MIWK  and  MWK  depend 
only  on  n,£,IDEG,  and  m. 

If  MFIT  is  called  then  X,  Z,W ,  R,  and  WK  are  single  precision  real  arrays.  Otherwise, 
if  DMFIT  is  called  then  X,  Z,  W,  R,  and  WK  are  double  precision  arrays. 

IER  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IER  has  one  of  the  following  values: 

IER  =  0  The  desired  polynomial  was  obtained. 

IER  =  —  1  Not  all  the  basis  polynomials  could  be  used.  IDEG  is  the  degree 
of  the  polynomial  obtained.  This  setting  occurs  when  the  problem 
is  not  solvable  or  is  too  ill-conditioned  for  the  requested  degree. 

IER  =  1  Only  t  basis  polynomials  were  used.  A  polynomial  E(xi,  . . . ,  xn) 

was  obtained  which  solves  the  equations  F(x}'\  ...,xi^)  =  2,- 
for  t  =  1,  . . . ,  t. 

IER  =  2  (Input  error)  IDEG  <  0  and  m  <  0. 

IER  =  3  (Input  error)  n  <  I  or  t  <  1. 

IER  =  4  (Input  error)  LIWK  or  LWK  is  too  small.  Set  LIWK  >  MIWK 

and  LWK  >  MWK. 

When  an  input  error  is  detected,  the  routine  immediately  terminates. 

Remark.  When  IER  <  1  then  MEVAL  or  DMEVAL  may  be  used  to  compute  the  polyno¬ 
mial  obtained. 

Algorithm.  The  revised  Gram-Schmidt  orthogonalization  procedure  is  used. 

Programming.  MFIT  employs  the  routines  ALLOT,  BASIZ,  MTABLE,  GNRTP,  INCDG, 
SCALPM,SCALDN,and  DMFIT  employs  the  routines  ALLOT, B  AS  IZ,MTABLE,DGNRTP, 
DINCDG,  DSCALP,  DSCALD.  MFIT  and  DMFIT  are  modifications  by  A.  H.  Morris  of 
CONSTR,  written  by  Richard  H.  Bartels  (University  of  Waterloo)  and  John  J.  Jezioranski 
(Ontario  Cancer  Institute). 

References. 

(1)  Bartels,  R.  H.  and  Jezioranski,  J.  J.,  “Least  Squares  Fitting  using  Orthogonal  Multi¬ 
nomials,”  ACM  Trans.  Math  Software  11  (1985),  pp.  201-217. 

(2)  - ,  “Algorithm  634,  CONSTR  and  EVAL:  Routines  for  Fitting  Multinomials 

in  a  Least  Squares  Sense,”  ACM  Trans.  Math  Software  11  (1985),  pp.  218-228. 
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CALL  MEVAL(n,  KDEG,  m,  7,  XI,  kxi,  ZI,IND,IWK,  WK,LIWK,LWK,T) 

CALL  DMEVAL(n,  KDEG,  m,  l,  XI,  kxi,  ZI,IND,IWK, WK,LIWK,LWK,T) 

MEVAL  (DMEVAL)  computes  the  polynomial  obtained  by  MFIT  (DMFIT),  or  a  por¬ 
tion  thereof.  Let  IDEG  and  m  be  the  output  values  given  by  MFIT  (DMFIT). 

The  argument  m  is  a  variable.  If  KDEG  <  0  then  it  is  assumed  that  1  <  m  <  m  and 
that  the  polynomial  using  the  first  m  basis  polynomials  is  to  be  computed.  In  this  case, 
the  polynomial  computed  is  the  best  least  squares  fit  for  the  basis  polynomials  involved. 

If  KDEG  >  0  then  it  is  assumed  that  KDEG  <  IDEG.  In  this  case,  when  the  routine 
terminates,  m  =  the  number  of  basis  polynomials  used.  If  m  <  m  (which  will  be  the  case 
when  KDEG  <  IDEG),  then  the  polynomial  computed  is  the  polynomial  of  degree  KDEG 
which  is  the  best  least  squares  fit. 

Usage.  If  IER  =  ±1  when  MFIT(DMFIT)  terminates,  then  the  setting  KDEG  =  IDEG 
normally  causes  an  error  to  occur  since  m  >  m.  Hence,  if  it  is  desired  that  the  full 
polynomial  obtained  by  MFIT(DMFIT)  be  computed,  no  matter  whether  the  value  for  IER 
is  0  or  ±1,  then  KDEG  should  be  assigned  a  negative  value  and  m  =  m. 

It  is  assumed  that  the  polynomial  is  to  be  computed  at  the  points  (x^\  . . .  ,r^) 
for  i  =  1,  XI  is  an  £  x  n  matrix  whose  ith  row  contains  the  point  (x^*\  . . .  ,zn^). 

The  argument  kxi  is  the  number  of  rows  in  the  dimension  statement  for  XI  in  the  calling 
program.  ZI  is  an  array  of  dimension  £  or  larger.  When  the  routine  terminates,  ZI(») 
contains  the  value  of  the  polynomial  at  the  point  [x^,. . .  ,xj^)  for  1  =  1,  ...,£. 

IWK  and  WK  are  the  arrays  obtained  from  MFIT  or  DMFIT.  LIWK  is  the  dimension 
of  IWK  and  LWK  the  dimension  of  WK.  T  is  an  array  of  dimension  n  or  larger  that  is  a 
work  space  for  the  routine. 

If  MEVAL  is  called  then  XI,  ZI,  WK  and  T  are  single  precision  arrays.  Otherwise,  if 
DMEVAL  is  called  then  XI,  ZI,  WK  and  T  are  double  precision  arrays. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  has  one  of  the  following  values: 

IND  =  0  The  desired  computation  was  performed. 

IND  =  —  1  (Input  error)  m  <  1  or  m  >  m. 

IND  =  —  2  (Input  error)  n  <  1  or  £  <  1. 

Programming.  MEVAL  calls  the  subroutine  MEVAL1  and  DMEVAL  calls  the  subroutine 
DMEVLl.  MEVAL  and  DMEVAL  are  modifications  by  A.  H.  Morris  of  EVAL,  written 
by  Richard  H.  Bartels  (University  of  Waterloo)  and  John  J.  Jezioranski  (Ontario  Cancer 
Institute). 
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EVALUATION  OF  INTEGRALS  OVER  FINITE  INTERVALS 


QAGS,  QSUBA,  and  DQAGS  are  available  for  computing  integrals  over  finite  inter¬ 
vals.  The  subroutine  QAGS  and  function  QSUBA  yield  single  precision  results,  and  the 
subroutine  DQAGS  yields  double  precision  results.  These  procedures  are  adaptive.  In  such 
procedures,  the  selection  of  the  points  at  which  the  integrand  is  evaluated  depends  on  the 
nature  of  the  integrand. 

CALL  QAGS(E,  a,  b,  AERR,RERR,  z,  ERROR, NUM,IERR,  £,  m,  n,  I WK,WK) 

F(x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  single 
precision  real  numbers.  The  purpose  of  QAGS  is  to  compute  the  integral  f*  F{x)dx.  F 
need  not  be  defined  at  a  and  b,  and  it  is  not  required  that  a  <  b.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used,  and  z  is 
a  variable.  When  QAGS  is  called,  z  is  assigned  the  value  obtained  for  fb  E(z)  dx.  The 
routine  attempts  to  obtain  a  value  z  which  satisfies  |  /  E(i)  dx  —  z\  <  maz{AERR,RERR  ■ 
|  f  F(x)  dx|}.  It  is  assumed  that  AERR  >  0  and  RERR  >  0.  If  one  wants  accuracy  to  k 
significant  digits  then  set  RERR  =  10-fe. 

ERROR  and  NUM  are  variables.  When  QAGS  terminates,  ERROR  is  the  estimated 
absolute  error  of  the  result  and  NUM  is  the  number  of  points  at  which  F  was  evaluated. 

IWK  is  an  array  of  dimension  £  and  WK  is  an  array  of  dimension  m.  IWK  and  WK  are 
work  spaces  for  the  routine.  The  input  argument  £  is  the  maximum  number  of  subintervals 
in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that  £  >  1  and  m  >  4£. 
The  argument  n  is  a  variable.  When  QAGS  terminates,  n  =  the  number  of  subintervals 
that  appeared  in  the  partition.  Normally  n  <  100. 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 

The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

The  interval  of  integration  was  partitioned  into  £  subintervals. 

More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

The  integral  has  been  computed,  but  because  of  roundoff  error 
QAGS  is  not  certain  of  the  accuracy  of  the  result.  The  error  may 
be  greater  than  that  reported  by  ERROR. 

Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained. 

The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 


IERR  =  0 
IERR  =  1 

IERR  =  2 

IERR  =  3 
IERR  =  4 
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IERR  =  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 

IERR  =  6  (Input  Error)  Either  t  <  1,  m  <  At,  AERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  z,  ERROR,  NUM,  and  n  are  set  to  0. 

Note.  F  may  have  singularities  at  a  and  b.  However,  it  is  recommended  that  no  singularities 
appear  in  the  interior  of  the  interval  of  integration. 

Algorithm.  The  21  point  Kronrod  rule  and  e-algorithm  of  P.  Wynn  are  used. 

Programming.  QAGS  employs  the  subroutines  QAGSE,  QK21F,  QPSRT,  and  QELG. 
These  routines  were  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katho- 
lieke  Universiteit  Leuven,  Heverlee,  Belgium).  The  function  SPMPAR  is  also  used. 

Reference.  Piessens,  R.,de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration ,  Springer-Verlag,  1983. 

QSUBA(F,  a,b,  RERR, MCOUNT, ERROR, IND) 

F(x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  single 
precision  real  numbers.  The  purpose  of  QSUBA  is  to  compute  the  integral  f*  F(x)  dx.  F 
need  not  be  defined  at  the  points  a  and  b.  However,  it  is  assumed  that  a  <  b.  F  must  be 
declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

RERR  is  the  relative  error  tolerance  to  be  satisfied.  It  is  assumed  that  RERR  >  0.  If 
one  wants  accuracy  to  k  significant  digits  then  set  RERR  =  10~fc. 

The  input  argument  MCOUNT  is  the  maximum  number  of  points  at  which  F  may  be 
evaluated.  It  is  recommended  that  MCOUNT  >  1000. 

ERROR  is  a  variable  that  is  set  by  QSUBA.  If  the  value  of  QSUBA  is  not  0  then 
ERROR  is  a  rough  estimate  of  the  relative  error  of  the  computed  result.  Otherwise,  if  the 
value  of  QSUBA  is  0  then  ERROR  is  rough  estimated  of  the  absolute  error. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  QSUBA  terminates,  IND 
has  one  of  the  following  values: 

IND  =  0  The  function  QSUBA  is  satisfied  that  the  integral  has  been  com¬ 
puted  to  the  desired  accuracy. 

IND  =  1  The  integral  has  been  computed,  but  QSUBA  is  not  certain  of  the 
accuracy  of  the  result. 

IND  =  2  F(x)  was  evaluated  at  MCOUNT  points.  More  evaluations  are 
needed  to  complete  the  computation  of  the  integral. 

IND  =  3  The  function  QSUBA  cannot  compute  the  integral  to  the  desired 
accuracy. 

If  IND  =  0  or  1  then  the  function  QSUBA  is  assigned  the  value  obtained  for  the  integral. 
If  IND  =  2  then  QSUBA  has  for  its  value  the  most  recent  acceptable  partial  estimate  made 
of  the  integral.  Otherwise,  if  IND  =  3,  then  QSUBA  has  for  its  value  the  best  estimate  of 
the  value  of  the  integral  that  it  can  make. 
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Note.  QSUBA  assumes  that  F  and  its  derivatives  have  no  singularities  in  the  closed  interval 
[a, b}.  If  this  is  not  the  case  then  QAGS  should  be  used.  QSUBA  is  recommended  for 
computing  integrals  such  as  J010  sin  yz2  dx  whose  integrands  are  finitely  oscillatory. 

Algorithm.  Gaussian  quadrature  is  employed. 

Programming.  QSUBA  calls  the  subroutine  QUAD.  QSUBA  and  QUAD  were  written 
by  T.  N.  L.  Patterson  (Queen’s  University,  Belfast,  Northern  Ireland),  and  QSUBA  was 
modified  by  A.  H.  Morris.  The  function  SPMPAR  is  used. 

Reference.  Patterson,  T.  N.  L., “Algorithm  for  Automatic  Numerical  Integration  Over  a 
Finite  Interval,”  Comm.  ACM  16  (1973),  pp.694-699. 

CALL  DQAGS  (E, a,  6, AERR, RERR, z, ERROR, NUM, IERR, £,  m,  n,IWK,WK) 

E(z)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  double 
precision  real  numbers.  The  purpose  of  DQAGS  is  to  compute  the  integral  /  E(z)  dx.  The 
arguments  a  and  b  are  double  precision  real  numbers.  F  need  not  be  defined  at  a  and  b, 
and  it  is  not  required  that  a  <  b.  F  must  be  declared  in  the  calling  program  to  be  of  types 
DOUBLE  PRECISION  and  EXTERNAL. 

AERR  and  RERR  are  double  precision  real  numbers  and  z  is  a  double  precision  vari¬ 
able.  AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  When 
DQAGS  is  called,  z  is  assignee!  the  value  obtained  for  fa  F(x)  dx.  The  routine  attempts  to 
obtain  a  value  z  which  satisfies  |  /  F(x)  dx  —  z\  <  max{AERR,  RERR  •  \  f  F(x)  <fxj}.  It  is 
assumed  that  AERR  >  0  and  RERR  >  0. 

ERROR  is  a  double  precision  variable  and  NUM  an  integer  variable.  When  DQAGS 
terminates,  ERROR  is  the  estimated  absolute  error  of  the  result  and  NUM  is  the  number 
of  points  at  which  F  was  evaluated . 

IWK  is  an  integer  array  of  dimension  £  and  WK  a  double  precision  array  of  dimension 
m.  IWK  and  WK  are  work  spaces  for  the  routine.  The  argument  £  is  the  maximum  number 
of  subintervals  in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that 
£  >  1  and  m  >  4£.  The  argument  n  is  a  variable.  When  DQAGS  terminates,  n  =  the 
number  of  subintervals  that  appeared  in  the  partition.  Normally  n  <  100. 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 

The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

The  interval  of  integration  was  partitioned  into  £  subintervals. 

More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

The  integral  has  been  computed,  but  because  of  roundoff  error 
DQAGS  is  not  certain  of  the  accuracy  of  the  result.  The  error 
may  be  greater  than  that  reported  by  ERROR. 


IERR  =  0 
IERR  =  1 

IERR  =  2 
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Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained. 

The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 

(Input  Error)  Either  t  <  1,  m  <  U,  AERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  z,  ERROR,  NUM,  and  n  are  set  to  0. 

Remarks.  F  may  have  singularities  at  a  and  b.  However,  it  is  recommended  that  no  singu¬ 
larities  appear  in  the  interior  of  the  interval  of  integration.  DQAGS  is  a  double  precision 
version  of  the  routine  QAGS. 

Algorithm.  The  21  point  Kronrod  rule  and  e-algorithm  of  P.  Wynn  are  used. 

Programming.  DQAGS  employs  the  subroutines  DQAGSE,DQK21,DQPSRT, and  DQELG. 
These  subroutines  are  double  precision  versions  of  the  subroutines  QAGSE,QK21F,QPSRT, 
and  QELG,  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katholieke  Uni- 
versiteit  Leuven,  Heverlee,  Belgium).  The  function  DPMPAR  is  also  used. 

Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration,  Springer- Verlag,  1983. 


IERR  =  3 
IERR  =  4 

IERR  =  5 
IERR  =  6 
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EVALUATION  OF  INTEGRALS  OVER  INFINITE  INTERVALS 


The  subroutines  QAGI  and  DQAGI  are  available  for  computing  integrals  over  infinite 
intervals.  QAGI  yields  single  precision  results  and  DQAGI  yields  double  precision  results. 
QAGI  and  DQAGI  are  adaptive  routines. 


CALL  QAGI(E, a, MO, AERR, RERR, z, ERROR, NUM, IERR, £,m,n, IWK, WK) 

F(x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  real 
numbers.  The  argument  a  is  a  real  number,  z  is  a  variable,  and  MO  may  be  1,  —1,  or 
2.  When  QAGI  is  called,  z  is  assigned  the  value  F(x)  dx  if  MO  =  1  and  the  value 
F(x)  dx  if  MO  =  —1.  Otherwise,  if  MO  =  2  then  z  is  assigned  the  value  F(x)  dx. 
If  MO  =  ±1  then  F  need  not  be  defined  at  o.  Otherwise,  if  MO  =  2  then  a  is  not  used.  F 
must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 


AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  The 
subroutine  attempts  to  obtain  a  value  z  which  satisfies  |  f  F(x)  dx—z |  <  max{AERR,RERR- 
|  f  F(x)  dx\}.  It  is  assumed  that  AERR  >  0  and  RERR  >  0.  If  one  wants  accuracy  to  k 
significant  digits  then  set  RERR  =  10-fc. 

ERROR  and  NUM  are  variables.  When  QAGI  terminates,  ERROR  is  the  estimated 
absolute  error  of  the  result  and  NUM  is  the  number  of  points  at  which  F  was  evaluated. 

IWK  is  an  array  of  dimension  £  and  WK  is  an  array  of  dimension  m.  IWK  and  WK  are 
work  spaces  for  the  routine.  The  input  argument  £  is  the  maximum  number  of  subintervals 
in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that  £  >  1  and  m  >  4 £. 
The  argument  n  is  a  variable.  When  QAGI  terminates,  n  =  the  number  of  subintervals 
that  appeared  in  the  partition.  Normally  n  <  100. 


IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 


IERR  =  0 
IERR  =  1 

IERR  =  2 

IERR  =  3 
IERR  =  4 

IERR  =  5 


The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

The  interval  of  integration  was  partitioned  into  £  subintervals. 
More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

The  integral  has  been  computed,  but  because  of  roundoff  error 
QAGI  is  not  certain  of  the  accuracy  of  the  result.  The  error  may 
be  greater  than  that  reported  by  ERROR. 

Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained. 

The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 
In  this  case,  the  value  for  z  may  be  meaningless. 
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IERR  =  6  (Input  Error)  Either  £  <  1,  m  <  4£,  AERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  z,  ERROR,  NUM,  and  n  are  set  to  0. 

Note.  F  may  have  a  singularity  at  a  when  MO  =  ±1.  However,  it  is  recommended  that  no 
singularities  appear  in  the  interior  of  the  interval  of  integration. 

Algorithm.  The  integrals  are  transformed  as  follows: 

F{x)dx  =  jo  F(a  —  1  +  l/t)-^ 

J‘^F(x)dx  =  £  F(a  +  l-l/t)£ 

/_!  f(x) dx = /Vh + i/t) + F{ [i  ■  mw 

The  transformed  integrals  are  computed  by  the  15  point  Kronrod  rule  and  the  e-algorithm 
of  P.  Wynn. 

Programming.  QAGI  employs  the  subroutines  QAGIE,  QK15I,  QPSRT,  and  QELG.  These 
routines  were  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katholieke 
Universiteit  Leuven,  Heverlee,  Belgium).  The  function  SPMPAR  is  also  used. 

Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK :  A  Subroutine  Package  for  Automatic  Integration,  Springer- Verlag,  1983. 

CALL  DQAGI(E, a, MO, AERR, RERR, z, ERROR, NUM, IERR, £,m,n,IWK1WK) 

F(x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  double 
precision  real  numbers.  The  argument  a  is  a  double  precision  real  number,  z  is  a  double 
precision  variable,  and  MO  may  be  1,  -1,  2.  When  DQAGI  is  called,  z  is  assigned  the  value 
E(i)  dx  if  MO  ■=  1  and  the  value  F(x)  dx  if  MO  =  —  1.  Otherwise,  if  MO  =  2  then 
z  is  assigned  the  value  F(x)  dx.  If  MO  =  ±1  then  F  need  not  be  defined  at  o.  F  must 
be  declared  in  the  calling  program  to  be  of  types  DOUBLE  PRECISION  and  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  The  sub¬ 
routine  attempts  to  obtain  a  value  z  which  satisfies  |  /  F(x)  dx  -  z\  <  max{AERR,RERR- 
I  /  dx|}.  It  is  assumed  that  AERR  and  RERR  are  nonnegative  double  precision  num¬ 

bers. 

ERROR  is  a  double  precision  variable  and  NUM  an  integer  variable.  When  DQAGI 
terminates,  ERROR  is  the  estimated  absolute  error  of  the  result  and  NUM  is  the  number 
of  points  at  which  F  was  evaluated. 

IWK  is  an  integer  array  of  dimension  £  and  WK  a  double  precision  array  of  dimension 
m.  IWK  and  WK  are  work  spaces  for  the  routine.  The  argument  £  is  the  maximum  number 
of  subintervals  in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that 
£  >  1  and  m  >  4 £.  The  argument  n  is  a  variable.  When  DQAGI  terminates,  n=  the  number 
of  subintervals  that  appeared  in  the  partition.  Normally  h  <  100. 
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IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  of  the  following  values: 

IERR  =  0  The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

IERR  =  1  The  interval  of  integration  was  partitioned  into  i  subintervals. 

More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

IERR  =  2  The  integral  has  been  computed,  but  because  of  roundoff  error 
DQAGI  is  not  certain  of  the  accuracy  of  the  result.  The  error 
may  be  greater  than  that  reported  by  ERROR. 

IERR  =  3  Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained. 

IERR  =  4  The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

IERR  =  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 

IERR  =  6  (Input  Error)  Either  l  <  1,  m  <  4£,  AERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  z,  ERROR,  NUM,  and  n  are  set  to  0. 

Remarks.  F  may  have  a  singularity  at  a  when  MO  =  ±1.  However,  it  is  recommended 
that  no  singularities  appear  in  the  interior  of  the  interval  of  integration.  DQAGI  is  a  double 
precision  version  of  the  routine  QAGI. 

Programming.  DQAGI  employs  the  routines  DQAGIE,DQK15I,DQPSRT,  and  DQELG. 
These  subroutines  are  double  precision  versions  of  the  subroutines  QAGIE,  QK15I,  QP- 
SRT,  and  QELG,  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katholieke 
Universiteit  Leuven,  Heverlee,  Belgium).  The  function  DPMPAR  is  also  used. 

Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration ,  Springer- Verlag,  1983. 
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EVALUATION  OF  DOUBLE  INTEGRALS  OVER  TRIANGLES 

Let  f(x,y )  be  a  real-valued  function  defined  on  a  triangle  T.  Then  the  subroutine 
CUBTRI  is  available  for  computing  the  integral  fJT  f(x,y)dxdy.  CUBTRI  is  an  adaptive 
routine. 

CALL  CUBTRI(F,  T, e , MAX, A, ERR, n,W,£, IDATA, RDATA, IERR) 

T  is  a  2-dimensional  real  array  of  dimension  2x3  where  T(l,j)  and  T(2,j)  are  the  x 
and  y  coordinates  of  the  jth  vertex  of  the  given  triangle  (j  =  1,2,3). 

IDATA  and  RDATA  are  arrays  provided  by  the  user  containing  any  integer  or  real  data 
needed  for  computing  the  integrand  f{x,y).  The  arrays  may  be  of  any  size.  F  is  a  user 
defined  real-valued  function  having  the  arguments  x,  y, IDATA, RDATA.  It  is  assumed  that 
F(x,y, IDATA, RDATA)  =  /(x,  y)  for  any  point  (x,y)  in  the  triangle  of  integration  T.  F 
must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  input  argument  e  is  the  error  tolerance  to  be  satisfied,  and  A  is  a  variable.  When 
CUBTRI  is  called,  A  is  assigned  the  value  obtained  for  ffT  f{x,y)  dxdy.  The  routine 
attempts  to  obtain  a  value  A  which  satisfies  \JJ  /(x,  y)  dxdy  —  A\  <  max{e,e|A|}.  Thus 
if  | Aj  <  1  then  e  is  an  absolute  tolerance,  whereas  if  |A|  >  1  then  e  is  a  relative  tolerance. 
If  one  wants  k  digit  accuracy  then  set  e  =  10~fc.  ERR  is  a  variable.  When  CUBTRI 
terminates,  ERR  is  the  estimated  error  |  ff  /(x,y)  dx  dy  —  A|  of  the  result. 

The  input  argument  MAX  is  the  maximum  number  of  points  (x,  y)  at  which  F  may 
be  evaluated,  and  n  is  a  variable.  On  an  initial  call  to  CUBTRI,  the  user  must  set  n  =  0. 
When  the  routine  terminates,  n  will  have  for  its  value  the  number  of  points  at  which  F  was 
evaluated.  (For  subsequent  calls  concerning  the  same  integral,  see  below.) 

W  is  an  array  of  dimension  £  for  internal  use  by  the  routine.  The  input  argument  £ 
specifies  the  maximum  number  of  subtriangles  in  which  the  triangle  of  integration  T  may 
be  partitioned.  The  subtriangles  are  stored  in  W,  each  subtriangle  requiring  6  storage 
locations.  Thus  £/6  is  an  estimate  of  the  maximum  number  of  subtriangles  that  might  have 
to  be  stored  (£  <  max{l,3nj  +  1}  where  m  =  (MAX/19  —  l)/4). 

IERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  IERR  has  one  of  the  following  values: 

IERR  =  0  The  integral  was  computed  to  the  desired  accuracy. 

IERR  =  1  MAX  is  too  small.  F  must  be  evaluated  at  more  points. 

IERR  =  2  The  storage  space  W  is  full.  Its  dimension  £  must  be  increased. 

IERR  =  3  Further  subdivision  of  the  subtriangles  impossible.  This  normally 
occurs  when  /(x,y)  has  a  singularity  in  the  region.  The  situation 
can  frequently  be  eliminated  by  placing  the  singularity  at  a  vertex 
of  the  triangle  of  integration  T. 

IERR  =  4  No  further  improvement  in  accuracy  is  possible  because  of  roundoff 
error  in  the  computation  of  F  or  the  irregular  behavior  of  F. 
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IERR  —  5  No  further  improvement  in  accuracy  is  possible  because  subdivi¬ 
sion  does  not  change  the  estimated  integral  value  A.  Machine 
accuracy  has  probably  been  reached. 

After  an  initial  call  to  CUBTRI,  the  routine  may  be  recalled  to  continue  the  compu¬ 
tation  of  JfTf( x,y)  dxdy.  When  the  routine  is  recalled,  the  value  of  n  obtained  on  the 
previous  call  to  CUBTRI  is  used  for  the  next  call.  This  value  for  n  tells  the  routine  where 
computation  should  be  resumed  (using  the  information  previously  stored  in  W).  At  least 
one  of  the  values  e,  MAX,  or  t  must  be  modified  before  CUBTRI  is  recalled.  F,  T,  n,  W, 
IDATA,  and  RDATA  may  not  be  changed  when  the  routine  is  recalled. 

Remark.  F  may  have  a  singularity  at  one  of  the  vertices  of  T  (such  as  in  the  case  when  we 
are  computing  /0  (i2+3y2)-1/2  dydx).  However,  it  is  recommended  that  no  singularities 

appear  in  the  interior  of  the  triangle  of  integration. 

Algorithm.  The  7-point  degree  5  rule  of  Radon  and  a  new  19-point  degree  8  rule  are  used. 

Programming.  CUBTRI  calls  the  function  RNDERR  and  subroutine  CUBRUL.  Informa¬ 
tion  is  saved  in  labeled  common  blocks.  The  block  names  are  CUBSTA  and  CUBATB.  The 
routines  were  written  by  D.  P.  Laurie  (National  Research  Institute  for  the  Mathematical 
Sciences,  Pretoria,  South  Africa). 

Reference.  Laurie,  D.  P.,  “Algorithm  584,  CUBTRI:  Automatic  Cubature  over  a  Triangle,” 
ACM  Trans.  Math  Software  8  .(1982),  pp.  210-218. 
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SOLUTION  OF  FREDHOLM  INTEGRAL  EQUATIONS 
OF  THE  SECOND  KIND 


If  k(s,t)  and  f(s)  are  continuous  real- valued  functions  for  a  <  s  <  b  and  a  <  t  <  b, 
then  the  equation  to  be  solved  is 


:(s) 


f 


k(s,t)x(t)dt  =  f(s ) 


for  a  <  s  <  b.  Let  K  be  the  operator  defined  by  (Kx)(s)  =  /  k(s,t)x(t)  dt  for  any  real¬ 
valued  function  x  continuous  on  [a,  6].  Then  (ifx)(s)  is  continuous  for  ct  <  s  <  b,  and 
k  is  called  the  kernel  of  K.  Also  the  above  integral  equation  can  be  written  in  the  form 
(I  —  K)x  =  f  where  I  is  the  identity  operator.  This  equation  has  a  unique  solution  if  and 
only  if  /  —  K  is  1  -  1,  in  which  case  x  =  (I  -  K)~l  f .  The  subroutine  IESLV  is  available 
for  computing  this  solution. 

Remark.  If  C[a,6]  is  the  normed  space  of  real- valued  functions  x  continuous  on  [a,  b] 
and  having  the  norm  ||x||  =  max{  |x(t)[  :  a  <  t  <  6},  then  If  is  a  compact  mapping 

C[a,6]  — *  C[a,b ]  having  the  norm  ]|if||  =  fa  lfcMI  dL 

a<s<b  J a 

CALL  IESLV(fc,  f,  a,  6,EPS,IFLAG,5,  X,  l,  N,  M,NF,MF,NORMK,WK,IERR) 

It  is  assumed  that  a  <  b,  and  that  k(s,t)  and  f(s)  are  user  defined  real-valued  functions 
for  a  <  s,  t  <  b.  It  is  recommended  that  k  and  /  be  several  times  continuously  differentiable. 
The  functions  k  and  /  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

EPS  is  a  variable  and  IFLAG  an  input  argument  whose  values  are  0  and  1.  On  input 
EPS  is  the  error  tolerance  that  the  solution  must  satisfy.  If  IFLAG  =  0  then  EPS  is  an 
absolute  tolerance.  Otherwise,  if  IFLAG  =  1  then  EPS  is  a  relative  tolerance.  If  IESLV 
solves  the  equation,  then  on  output  EPS  is  the  estimated  error  of  the  result. 

Before  the  remaining  arguments  s,x,£,  ...  can  be  described,  it  is  necessary  to  give 
a  brief  outline  of  the  algorithm  used.  When  IESLV  is  called,  the  integral  equation  is 
approximated  by 


(*)  *n(«)  -  w,nk(S)  tjn)xn[tjn)  =  f(s ) 

3=1 

for  a  <  s  <  b.  Here  wjn  and  tjn  are  the  weights  and  nodes  of  Gauss-Legendre  quadrature. 
This  equation  is  treated  as  an  interpolation  for  x(s)  in  terms  of  the  values  x„(tyn).  These 
values  are  obtained  by  solving  the  equations 


(**) 


xn  (^in)  ^  ^  Wjnk(tjn,  tjn')Xn(tjn')  —  /(t,’n) 

3=1 
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for  i '  =  1,  . . . ,  n.  This  system  of  equations  can  be  solved  directly  or  iteratively.  The  following 
algorithm  is  used: 

(1)  Set  n  =  2  and  go  to  (2). 

(2)  The  n  equations  are  solved  directly.  Then  set  m  =  2n  and  solve  the  m  equations  (**) 
iteratively.  If  the  rate  of  convergence  is  sufficiently  rapid  or  n  cannot  be  increased, 
then  go  to  (3).  Otherwise,  set  n  =  m,  and  go  to  (2). 

(3)  Here  n  remains  fixed.  Repeatedly  double  the  value  of  m  and  solve  the  m  equations  (**) 
iteratively  until  convergence  occurs,  m  cannot  be  increased,  or  the  iterations  diverge. 

When  the  algorithm  terminates,  values  will  have  been  computed  for  the  nodes 

t,m(f  =  1,  .  •  •  ,m).  Then  from  (*),  x(s)  «  xm(s)  can  be  interpolated  for  a  <  s  <  b. 

N  and  M  are  input  arguments,  and  WK  is  an  array  that  is  a  work  space  for  the 
routine.  N  and  M  are  upper  limits  for  n  and  m  in  the  algorithm,  and  WK  is  of  dimension 
5 N2  +  9 (IV  +  M )  or  larger.  It  is  assumed  that  M  >  N  >  2.  Since  n  and  m  are  always 
powers  of  2,  N  and  M  need  only  be  set  to  powers  of  2.  However,  this  is  not  required. 

S  and  X  are  arrays,  and  £  is  a  variable.  On  input  it  is  assumed  that  £  >  0.  If  £  >  0  then 
S  is  assumed  to  contain  £  points  s\,  . . .  ,st  at  which  the  solution  x(s)  is  to  be  evaluated. 
Also  X  is  assumed  to  be  an  array  of  dimension  £  or  larger.  When  IESLV  terminates,  X 
contains  the  values  obtained  for  x(si),  . . . ,  x(s«).  (This  is  true  irregardless  of  whether  or 
not  the  desired  accuracy  has  been  achieved.)  Otherwise,  if  £  =  0  then  S  and  X  are  assumed 
to  be  arrays  of  dimension  M  or  larger.  When  IESLV  terminates  £  =  the  final  value  obtained 
for  m,  S  contains  the  Gaussian  nodes  tit{i  ~  1,  ...  ,£),  and  X  contains  the  values  obtained 
for  x(tu). 

NF  and  MF  are  variables.  When  the  routine  terminates,  NF  is  the  final  value  for  n 
and  MF  the  final  value  for  m. 

NORMK  is  a  real  variable.  If  £  >  0  on  input,  then  when  IESLV  terminates,  NORMK 
is  an  approximation  for  ||iif||.  Otherwise,  if  £  =  0  then  NORMK  =  0. 

IERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IERR  has  one  of  the  following  values: 

IERR  =  0  The  solution  was  obtained  to  the  desired  accuracy.  EPS  is  the 
estimated  error  of  the  result. 

IERR  =  1  The  solution  was  not  obtained  to  the  desired  accuracy.  EPS  is  the 
estimated  error  of  the  result. 

IERR  =  2  The  solution  was  not  obtained  to  the  desired  accuracy.  It  is  not 
clear  what  accuracy  (if  any)  has  been  achieved.  EPS  has  been  set 
to  0. 

IERR  =  3  The  input  value  for  EPS  was  too  small.  This  may  be  due  to  ill- 
conditioning  of  the  integral  equation.  The  value  of  EPS  was  reset 
to  a  more  realistic  tolerance,  which  the  solution  satisfied. 

IERR  =  4  The  solution  z(s)  was  obtained  at  the  Gaussian  nodes  to  the  de¬ 
sired  precision.  However,  the  interpolation  process  may  not  pre¬ 
serve  this  accuracy  for  the  evaluation  of  x(s)  for  other  points  s. 

EPS  is  the  estimated  error  of  the  solution  at  the  Gaussian  nodes. 
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IERR  =  5  The  solution  z(s)  was  not  obtained  to  the  desired  accuracy  at 
the  Gaussian  nodes.  EPS  i3  the  estimated  error  at  these  nodes. 

The  interpolation  process  may  not  preserve  this  accuracy  for  the 
evaluation  of  z(s)  for  other  points  s. 

IERR  =  6  The  input  value  for  EPS  was  too  small.  This  may  be  due  to  ill- 
conditioning  of  the  integral  equation.  The  value  of  EPS  was  reset 
to  a  more  realistic  tolerance,  which  the  solution  z(s)  satisfied  at 
the  Gaussian  nodes.  The  interpolation  process  may  not  preserve 
this  accuracy  for  the  evaluation  of  z(s)  for  other  points  a. 

Difficulties  can  arise,  causing  IERR  >  1,  when  the  integral  equation  is  ill-conditioned  or 
the  kernel  A:(s,i)  is  not  appropriate  for  standard  Gaussian  quadrature.  El-conditioning  can 
occur  when  the  operator  I  —  K  is  near  singular  or  the  norm  ||if||  is  exceedingly  large. 
Inappropriate  kernels  k(s,  t)  include  those  which  are  highly  oscillatory  or  not  continuously 
differentiable  for  s  and  t  in  the  open  interval  (o,  6). 

Programming.  IESLV  employs  the  subroutines  LEGS,  NSTERP,  WANDT, LEAVE,  ITERT, 
LNSYS  and  functions  RMIN,RNRM,CONEW.  The  routines  save  and  exchange  information 
in  labled  common  blocks.  The  block  names  are  XXINFO  and  XXLIN.  The  routines  were 
written  by  Kendall  E.  Atkinson  (University  of  Iowa),  and  modified  by  A.  H.  Morris.  The 
function  SPMPAR  is  also  used. 

Reference.  Atkinson,  K.  E.,“An  Automatic  Program  for  Linear  Fredholm  Integral  Equa¬ 
tions  of  the  Second  Kind,”  ACM  Trans.  Math  Software  2  (1976),  pp.  154-171. 
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THE  INITIAL  VALUE  SOLVERS  -  INTRODUCTORY  COMMENTS 


Let  y'(f)  =  f(t,y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  /(t,y)  =  and  y(t)  =  (yx (i),  ...,yn(t)).  Assume  that  y(a)  is 

known.  Then  for  b  ^  a  the  subroutines  ODE,  RKF45,  GERK,  SFODE,  and  SFODE1  are 
available  for  computing  y(6).  These  routines  are  adaptive  variable  step  differential  equations 
solvers.  The  remaining  subroutines  (RK  and  RK8)  are  fixed  order,  one  step  procedures. 
Given  a  value  y(f)  and  a  step  size  k,  the  one  step  procedures  compute  a  value  for  y(t  +  h). 
The  problem  of  selecting  an  appropriate  step  size  is  left  to  the  user.  Given  y(a)  and  b,  the  one 
step  routines  must  be  repeatedly  called  to  step  along  the  interval  from  a  to  b.  The  situation, 
however,  is  considerably  different  with  the  adaptive  routines.  ODE,  SFODE,  and  SFODE1 
are  variable  order,  variable  step  procedures,  and  RKF45  and  GERK  are  fixed  order,  variable 
step  procedures.  Given  y(a),  b,  and  the  error  tolerances  that  are  to  be  maintained,  these 
solvers  continually  adjust  their  orders  and  step  sizes  as  they  (automatically)  step  along  the 
interval  from  a  to  6. 

The  adaptive  routines  differ  in  their  capabilities.  ODE,  RKF45,  and  GERK  are  recom¬ 
mended  for  nonstiff  equations,  and  SFODE  and  SFODE1  for  stiff  equations.  If  one  does  not 
know  whether  the  equations  are  stiff,  then  ODE  should  be  tried.  ODE  maintains  greater 
accuracy  than  the  other  routines,  and  it  will  notify  the  user  if  the  equations  appear  to  be 
stiff.  ODE,  RKF45,  and  GERK  should  be  able  to  handle  mildly  stiff  problems  satisfactorily, 
but  they  are  decidedly  not  appropriate  for  extremely  stiff  problems.  SFODE  and  SFODE1 
are  the  only  routines  in  the  mathematics  library  that  are  capable  of  solving  extremely  stiff 
equations. 

If  the  equations  to  be  solved  are  nonstiff,  then  the  choice  between  ODE  and  RKF45 
depends  on  the  amount  of  accuracy  needed  and  the  cost  of  the  derivative  evaluations.  If 
the  accuracy  requirements  are  high  then  ODE  is  recommended.  However,  if  the  accuracy 
requirements  are  low  and  the  derivative  evaluations  are  inexpensive,  then  RKF45  may  be 
the  most  efficient  routine  for  the  problem.  RKF45  frequently  requires  more  derivative 
evaluations  than  ODE,  but  its  overhead  is  considerably  less  than  that  for  ODE. 

When  the  user  specifies  the  error  tolerances  to  be  satisfied,  normally  he  is  only  inter¬ 
ested  in  the  global  error  (the  accuracy  of  y(6)).  However,  the  adaptive  routines  employ 
the  tolerances  for  controlling  local  error  (the  error  generated  at  each  internal  step  in  the 
interval).  No  attempt  is  made  to  control  the  progressive  erosion  of  accuracy  that  can  occur 
when  the  steps  accumulate.  GERK  is  the  only  routine  that  estimates  the  global  error.  This 
routine  employs  the  same  Runge-Kutta-Fehlberg  formulae  used  by  RKF45.  GERK  is  2-3 
times  slower  than  RKF45,  but  it  is  more  accurate. 

Output  Considerations.  Generally,  when  the  user  has  a  system  of  equations  y'(t)  = 
/ (t,  y(£))  to  be  solved  (where  y(ao)  is  known),  he  wants  its  solution  at  a  sequence  of  points 
ai,  . . . ,  aff.  If  an  adaptive  routine  is  being  used,  then  the  routine  will  be  repeatedly  called 
to  step  along  the  axis  from  each  point  a,-  to  the  next.  If  ODE,  SFODE,  or  SFODE1  is 
being  employed,  then  the  number  and  closeness  of  the  output  points  ax,  . . .  ,ajv  should  be 
of  no  concern.  These  routines  partially  ignore  ai+i  in  the  selection  of  the  step  size  when 
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going  from  a;  to  aj+i.  Instead,  they  step  along  the  axis  using  the  largest  steps  that  are 
appropriate  (efficiency  and  accuracy  are  the  prime  concerns).  Normally  a»+1  is  passed  in 
the  process.  If  a,+i  is  passed  then  a  quick  interpolation  yields  the  desired  result  at  a,+i. 
Thus  the  process  of  solving  the  equations  for  at+i  when  y(a^)  is  known  may  require  that 
no  steps  be  taken  (a»+i  may  have  been  bypassed  on  a  previous  call  to  ODE,  SFODE,  or 
SFODE1),  or  it  may  require  that  one  or  more  steps  be  taken. 

The  situation  is  considerably  different  if  RKF45  or  GERK  is  used.  These  routines 
select  their  step  size  so  as  not  to  bypass  a,-+i  when  going  from  a<  to  ai+i.  Thus  the  output 
points  ai,  ... ,  aj y  may  be  so  close  to  one  another  as  to  force  inordinately  small  step  sizes 
(when  such  step  sizes  would  otherwise  not  be  needed).  If  this  occurs  then  the  efficiency  of 
RKF45  and  GERK  may  deteriorate  dramatically.  The  routines  will  notify  the  user  of  the 
situation,  and  the  user  will  be  left  with  the  following  options: 

(1)  Switch  to  an  adaptive  routine  such  as  ODE  which  performs  interpolation. 

(2)  Use  a  nonadaptive  one  step  routine  such  as  RK  or  RK8. 

(3)  Use  RKF45  or  GERK  in  a  one  step  mode  (this  capability  is  permitted). 

If  option  (3)  is  taken,  then  the  user  may  just  repeatedly  call  RKF45  or  GERK  (in  the  one 
step  mode)  until  a#  is  reached. 


460 


ADAPTIVE  ADAMS  SOLUTION  OF 
NONSTIFF  DIFFERENTIAL  EQUATIONS 

Let  y'(t)  =  f(t,  y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f(t,y)  =  (/i(t,y),  . . . ,  fn(t,y))  and  y(t)  =  (yi(t),  ...,yn(t)).  Assume  that  y(a)  is 
known.  Then  for  b  ^  a  the  subroutine  ODE  is  available  for  computing  y(6).  ODE  is 
recommended  for  nonstiff  equations.  The  algorithm  used  is  a  variable  order,  variable  step 
Adams  predictor-corrector  procedure. 

CALL  ODE^,  n,  Y,  T,  TOUT,RERR,AERR,IND,WK,IWK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Y,  DY) 

Y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi(i), . . .  ,yn(i)  for  the 
argument  t.  F  computes  the  derivatives  y[(t),  .  ..,y'n(t)  using  y'(f)  =  f(t,y(t))  and  stores 
the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

WK  is  an  array  of  dimension  100  +  21n  or  larger,  and  IWK  is  an  array  of  dimension 
5  or  larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  ODE. 

It  is  assumed  that  a  ^  b.  The  argument  Y  of  ODE  is  an  array  of  dimension  n,  and 
the  arguments  T, RERR, AERR, IND  are  variables.  (TOUT  need  not  be  a  variable.)  When 
ODE  is  initially  called,  it  is  assumed  that: 

T  —  a 

TOUT  =  b 

Y(l),  . . . ,  Y(n)  contain  the  values  yi(a), . . . ,  yn(a) 

RERR  =  the  relative  error  tolerance  to  be  satisfied 

AERR  =  the  absolute  error  tolerance  to  be  satisfied 

IND  =  ±1 

It  is  preferable,  both  for  efficiency  and  accuracy,  that  ODE  be  permitted  to  step  along  the 
axis  from  a  to  b  using  the  largest  steps  that  are  appropriate.  This  is  what  is  done  when 
IND  is  set  to  1.  If  IND  =  1  then  ODE  will  step  along  the  axis,  possibly  passing  b  and 
going  as  far  as  the  point  a  +  10(6  —  a).  If  6  is  passed,  then  the  solution  for  the  equations 
at  b  is  obtained  by  interpolation.  However,  IND  =  1  cannot  be  used  if  the  equations  are 
not  defined  at  all  points  between  b  and  a  +  10(6  —  a).  In  a  situation  such  as  this,  when 
integration  cannot  be  permitted  to  step  internally  past  TOUT,  IND  must  be  set  to  —1.  If 
IND  =  —  1  then  it  is  required  that  the  subroutine  F  be  defined  at  TOUT.  However,  F  need 
not  be  defined  at  points  t  past  TOUT.  If  the  equations  y'(t)  =  /(t,y(t))  are  not  defined  at 
t  =  TOUT,  then  it  should  suffice  to  let  F  set  each  DY(t)  =  0  when  t  =  TOUT.  A  solution 
(if  one  exists)  will  be  obtained  by  extrapolation. 

If  IND  is  positive  (negative),  then  when  ODE  terminates  IND  will  have  been  reset  by 
ODE  to  one  of  the  values  2, 3, 4, 5, 6, 7(2, —3, —4, —5, —6,7).  These  values  have  the  following 
meanings: 

IND  =  2  The  equations  have  been  solved  at  TOUT.  T  now  has  the  value 
TOUT  and  Y  contains  the  solution  at  TOUT. 

IND  =  ±3  The  error  tolerances  RERR  and  AERR  are  too  small.  T  is  set  to 
the  point  closest  to  TOUT  for  which  the  equations  were  solved 
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IND  =  ±4 

IND  =  ±5 


IND  =  ±6 

IND  =  7 


and  Y  contains  the  solution  at  the  point.  RERR  and  AERR  have 
been  reset  to  larger  acceptable  values. 

MAXNUM  steps  were  performed.1  More  steps  are  needed  to  reach 
TOUT.  T  is  set  to  the  point  closest  to  TOUT  for  which  the  equa¬ 
tions  were  solved  and  Y  contains  the  solution  at  the  point. 
MAXNUM  steps  were  performed.  More  steps  are  needed  to  reach 
TOUT.  T  is  set  to  the  point  closest  to  TOUT  for  which  the  equa¬ 
tions  were  solved  and  Y  contains  the  solution  at  the  point.  The 
equations  appear  to  be  stiff. 

ODE  did  not  reach  TOUT  because  AERR  =  0.  T  is  set  to  the 
point  closest  to  TOUT  for  which  the  equations  were  solved  and  Y 
contains  the  solution  at  the  point. 

No  computation  was  performed.  An  input  error  was  detected.  The 
user  must  correct  the  error  and  call  ODE  again. 


If  IND  =  ±3,  ±4,  ±5  then  to  continue  the  integration  just  call  ODE  again.  Similarly,  if 
IND  =  ±6  then  reset  AERR  to  be  positive  and  call  ODE  again.  In  these  cases  do  not  modify 
T,  K,IND.  The  output  values  for  these  parameters  are  the  appropriate  input  values  for  the 
next  call  to  ODE.  However,  AERR  and  RERR  may  always  be  modifed  when  continuing  an 
integration. 

If  the  equations  appear  to  be  stiff  (i.e.,  if  IND  =  ±5)  then  ODE  may  not  be  suitable 
for  solving  the  equations.  In  this  case  it  is  recommended  that  a  routine  designed  specifically 
for  stiff  equations  be  used. 


Whenever  IND  =  2  occurs,  then  the  equations  have  been  solved  at  TOUT  =  b.  WK 
and  IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and 
solving  the  equations  at  a  new  point  c.  To  continue  the  integration,  normally  one  need  only 
reset  TOUT  to  the  new  value  c  and  call  ODE  again.  Do  not  modify  T,  Y^IND.  The  output 
values  for  these  parameters  are  normally  the  appropriate  input  values  for  the  next  call  to 
ODE.  The  one  exception  is  when  the  equations  are  not  defined  at  points  past  c.  If  this 
occurs,  then  one  should  also  reset  the  output  value  IND  =  2  (from  the  last  call  to  ODE)  to 
the  input  value  IND  =  -2  for  the  next  call  to  ODE..  If  IND  is  reset  to  -2,  then  integration 
will  not  proceed  internally  past  the  new  TOUT  when  ODE  is  recalled.  In  this  case,  the 
subroutine  F  need  not  be  defined  for  points  past  TOUT.  However,  it  is  required  that  F  be 
defined  at  TOUT. 

If  after  going  from  a  to  b,  ODE  is  recalled  to  continue  the  integration  and  solve  the 
equations  at  a  new  point  c,  then  it  is  important  that  IND  he  set  to  ±2  for  the  next 
call  to  ODE.  Setting  IND  to  ±1  causes  the  integration  procedure  to  be  restarted,  thereby 
eliminating  the  information  being  saved  in  WK  and  IWK.  Restarting  not  only  can  take  more 
time,  but  also  can  lead  to  less  accurate  results.  If  IND  is  set  to  ±2,  then  the  integration 
procedure  restarts  itself  only  if  the  direction  of  integration  is  being  reversed  or  IND  was 
negative  when  ODE  was  last  recalled.  The  direction  of  integration  is  reversed  when  b  does 
not  lie  between  a  and  c. 

’‘Each  step  normally  requires  two  calls  to  the  subroutine  F .  Currently  the  internal  parameter  MAXNUM 
is  set  at  500. 
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If  one  has  a  choice  between  setting  IND  to  be  positive  or  negative,  then  always  set  IND 
to  be  positive.  Extrapolation  is  normally  involved  when  IND  is  negative.  The  extrapolation 
can  require  more  time  and  be  less  accurate  than  the  procedures  employed  when  IND  is 
positive. 

Input  Errors.  IND  =  7  when  one  of  the  following  conditions  is  violated: 

(1)»>1 

(2)  T  #  TOUT 

(3)  RERR  >  0  and  AERR  >  0 

(4)  RERR  and  AERR  are  not  both  0 

(5)  1  <  |IND|  <  5,  or  IND  =  ±6  and  AERR  >  0 

(6)  When  continuing  an  integration,  the  input  value  for  T  is  the  output  value  of  TOUT 
from  the  previous  call  to  ODE. 

The  last  condition  is  automatically  satisfied  if  the  user  has  not  inadvertently  modified  T. 

Error  Control.  Assuming  that  ODE  has  obtained  the  correct  value  for  y{t),  let  e,  denote  the 
error  generated  in  the  computation  Y (i)  of  y,(t  +  h)  for  *  =  1,  . . . ,  n  when  ODE  steps  from  t 
to  t  +  h.  The  routine  attempts  at  each  step  to  maintain  the  accuracy  E i(ei/tuf)2  <  1  where 
Wi  =RERR  \Y (:)|+AERR.  When  this  criterion  is  satisfied,  then  |e,j  <  Wi  for  t  =  1,  .. .  ,n. 
This  criterion  includes  as  special  cases  relative  error  (AERR  =  0)  and  absolute  error  (RERR 
=  0).  However,  if  AERR  =  0  and  Y(i)  =  0  for  some  then  iwt-  =  0  and  IND  =  ±6. 

When  going  from  T  to  TOUT,  ODE  continually  adjusts  and  readjusts  its  order  and 
step  size  so  as  to  maintain  accuracy  at  each  step.  However,  no  attempt  is  made  to  control 
the  progressive  erosion  of  accuracy  that  can  occur  when  the  steps  accumulate.  Since  the 
erosion  of  accuracy  can  be  significant,  at  times  one  may  wish  to  double-check  the  results 
by  rerunning  the  problem.  If  this  is  done,  then  in  the  second  run  ask  for  greater  accuracy. 

Programming.  ODE  employs  the  subroutines  DEI,  STEP1,  and  INTRP.  These  routines 
were  written  by  L.  F.  Shampine  and  M.  K.  Gordon  (Sandia  Laboratories).  The  function 
SPMPAR  is  also  used. 

Reference.  Shampine,  L.  F.,  and  Gordon,  M.  K.,  Computer  Solution  of  Ordinary  Dif¬ 
ferential  Equations,  W.  H.  Freeman  and  Company,  San  Francisco,  1975. 
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ADAPTIVE  RKF  SOLUTION  OF  NONSTIFF  DIFFERENTIAL  EQUATIONS 


Let  y'(t)  =  f(t,y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f{t,y)  =  (/i  (t,y),  . . . ,/n  ( t ,  y))  and  y(i)  =  (yi  (t),  . . .  ,y„  (i)).  Assume  that  y(a)  is 
known.  Then  for  b  ^  a  the  subroutine  RKF45  is  available  for  computing  y(6).  RKF45  was 
designed  for  solving  nonstiff  differential  equations  when  derivative  evaluations  are  inexpen¬ 
sive  and  the  accuracy  requirements  are  low  (less  than  8  significant  digits).  The  routine 
employs  the  fourth-fifth  order  Runge-Kutta-Fehlberg  formulae. 


CALL  RKF45(.F,  n,  Y,  T,  TOUT, RERR, AERR, IND, WK, IWK) 


The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,  K,DY) 

Y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi(t),  . . . ,  yn(t)  for  the 
argument  t.  F  computes  the  derivatives  y((t),  .  ..,y^(f)  using  y'(t)  =  /(t,y(f))  and  stores 
the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

WK  is  an  array  of  dimension  3  +  fin  or  larger,  and  IWK  is  an  array  of  dimension  5  or 
larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  RKF45. 

The  argument  Y  of  RKF45  is  an  array  of  dimension  n,  and  the  arguments  T,  RERR, 
IND  are  variables.  (TOUT  and  AERR  need  not  be  variables.)  When  RKF45  is  initially 
called,  it  is  assumed  that: 

T  =  a 
TOUT  =  b 

F(l),  ...,y(n)  contain  the  values  yi(o),  .  ..,y„(a) 

RERR  =  the  relative  error  tolerance  to  be  satisfied 
AERR  =  the  absolute  error  tolerance  to  be  satisfied 
IND  =  ±1 

Normally  IND  =  1.  However,  if  only  a  single  step  in  the  direction  of  TOUT  is  to  be  taken, 
then  set  IND  =  —  1. 


On  output  T  is  set  to  the  point  closest  to  TOUT  for  which  the  equations  were  solved, 
and  Y  contains  the  solution  at  T.  Also  IND  reports  the  status  of  the  results.  RKF45  sets 
IND  to  one  of  the  following  values: 


IND  =  2 

IND  =  -2 
IND  =  3 

IND  =  4 

IND  =  5 

IND  =  6 


The  equations  were  successfully  solved  at  TOUT.  T  now  has  the 
value  TOUT. 

A  single  step  in  the  direction  of  TOUT  was  taken. 

The  error  tolerance  RERR  was  too  small.  RERR  has  been  reset 
to  a  larger  acceptable  value. 

3000  derivative  evaluations  were  performed.  More  derivative  eval¬ 
uations  are  needed  to  reach  TOUT. 

RKF45  did  not  reach  TOUT  because  AERR  =  0.  AERR  must  be 
made  positive. 

Too  much  accuracy  has  been  requested.  AERR  and/or  RERR 
must  be  increased  in  value. 
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7  The  closeness  of  the  output  points  is  restricting  the  natural  step 
size  choice. 

8  No  computation  was  performed.  An  input  error  was  detected.  The 
user  must  correct  the  error  and  call  RKF45  again. 

If  IND  =  2  then  the  equations  have  neen  solved  at  TOUT  =  b.  The  arrays  WK  and 
IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and  solving 
the  equations  at  a  new  point  c.  To  continue  the  integration  the  user  need  only  reset  TOUT 
to  the  new  point  c  and  call  RKF45  again. 

If  IND  =  —2  then  to  continue  the  integration  another  single  step  just  call  RKF45 
again.  In  the  single  step  mode  (IND  =  -1,-2)  the  user  must  keep  in  mind  that  each  step 
taken  is  in  the  direction  of  the  current  TOUT.  Upon  reaching  TOUT  (which  is  indicated  by 
IND  being  set  to  2),  the  user  may  then  define  a  new  TOUT  and  set  IND  to  ±2  for  further 
integration. 

If  IND  =  3  or  4  then  to  continue  the  integration  just  call  RKF45  again.  However,  if 
IND  =  5  then  the  user  must  first  reset  AERR  to  be  positive  before  RKF45  can  be  recalled. 
If  IND  =  6  then  it  is  required  that  IND  be  reset  to  ±2  and  that  AERR  and/or  RERR 
be  increased  in  value.  If  this  is  not  done  then  the  run  will  be  terminated  by  a  STOP 
instruction! 

If  IND  =  7  then  the  user  should  either  switch  to  another  routine,  or  he  should  use  the 
one  step  mode,  setting  IND  =  -2  for  the  next  call  to  RKF45.  This  situation  is  discussed 
in  the  Initial  Value  Solvers  -  Introductory  Comments  section.  If  the  user  insists  on 
continuing  the  integration  with  RKF45  in  the  standard  multistep  mode,  then  it  is  required 
that  IND  be  reset  to  2  before  RKF45  is  recalled.  If  this  is  not  done  then  the  run  will  be 
terminated  by  a  STOP  instruction. 

If  after  going  from  a  to  b,  RKF45  is  recalled  to  continue  the  integration  and  solve 
the  equations  at  a  new  point  c,  then  it  is  important  that  IND  be  set  to  ±2  instead  of 
±1.  Setting  IND  —  ±1  causes  the  integration  process  to  be  restarted,  thereby  eliminating 
the  information  being  saved  in  WK  and  IWK.  Restarting  wastes  time  and  is  normally  not 
needed.  The  one  exception  is  when  the  direction  of  integration  is  to  be  reversed.  Then  the 
integration  must  be  restarted. 

Notes. 

(1)  AERR  and  RERR  can  be  modified  each  time  that  RKF45  is  called. 

(2)  When  continuing  an  integration,  one  may  switch  from  the  standard  multistep  mode 
(IND  =  2)  to  the  one  step  mode  (IND  =  —  2)  whenever  it  is  convenient  to  do  so. 

Input  Errors.  IND  =  8  occurs  when  one  of  the  following  conditions  is  violated: 

(1) n>l 

(2)  T  ^  TOUT  when  IND  #  ±1 

(3)  RERR  >  0  and  AERR  >  0 

(4)  IND  =  ±1, ±2, 3, 4,  ..., 8 


IND  = 
IND  = 
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Error  Control.  Pure  absolute  error  control  is  not  permitted.  If  RERR  =  0  then  RERR  is 
reset  to  the  smallest  tolerance  that  is  permitted  for  the  computer  being  used,  IND  is  set  to 
3,  and  the  routine  terminates. 

When  going  from  T  to  TOUT,  RKF45  continually  adjusts  and  readjusts  its  step  size  so 
as  to  maintain  accuracy  at  each  step.  Assuming  that  RKF45  has  obtained  the  correct  value 
for  y(f),  let  e,-  denote  the  error  generated  in  the  computation  of  t +  h)  for  *  =  1,  . . .  ,n 
when  RKF45  steps  from  t  to  t  +  h.  Then  at  each  step  the  error  is  controlled  so  that 


ly»-(*)l  +  ly»(*  +  /Ql 
2 


RERR  +  AERR 


for  i  =  1,  ...  ,n.  However,  no  attempt  is  made  to  control  the  progressive  erosion  of  accuracy 
that  can  occur  when  the  steps  accumulate.  Since  the  erosion  of  accuracy  can  be  significant, 
at  times  one  may  wish  to  double-check  the  results.  This  can  best  be  done  by  comparing  the 
results  obtained  by  RKF45  with  those  obtained  by  ODE  or  GERK.  If  ODE  is  used  then 
ask  for  greater  accuracy.  However,  if  GERK  is  used  then  the  current  error  tolerances  can 
be  used.  GERK  is  more  accurate  than  RKF45,  and  it  estimates  the  global  error  generated. 

Programming.  RKF45  employs  the  subroutines  RKFS  and  FEHL.  These  routines  were 
written  by  H.  A.  Watts  and  L.  F.  Shampine  (Sandia  Laboratories).  The  function  SPMPAR 
is  also  used. 

References.  Shampine,  L.  F.,and  Allen,  R.  C., Numerical  Computing:  An  Introduction, 
W.  B.  Sanders,  Philadelphia,  1973. 
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ADAPTIVE  RKF  SOLUTION  OF  NONSTIFF  DIFFERENTIAL  EQUATIONS 
WITH  GLOBAL  ERROR  ESTIMATION 

Let  y'(i)  =  f(t,y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f(t,y)  =  (/x  (i,y),  ...,/„  (t, y))  and  y(f)  =  (yx  (i),  . . . ,y„  (t)).  Assume  that  y(a)  is 
known.  Then  for  b  ^  a  the  subroutine  GERK  is  available  for  computing  y(b).  GERK  was 
designed  for  solving  nonstiff  differential  equations  when  derivative  evaluations  are  inexpen¬ 
sive  and  the  accuracy  requirements  are  low  (less  than  8  significant  digits).  The  routine 
employs  the  fourth-fifth  order  Runge-Kutta-Fehlberg  formulae.  GERK  estimates  the  accu¬ 
racy  of  the  solution  y(6). 

CALL  GERK(E,  n,Y,T,  TOUT, RERR,AERR, IND  ,GERROR,WK, IWK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Y,  DY) 

Y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi  (t),  ...,y„(t) 
for  the  argument  t.  F  computes  the  derivatives  yj(t),  . . . ,  y^(t)  using  y'(t)  =  f(t,y(t)) 
and  stores  the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

WK  is  an  array  of  dimension  3  +  8n  or  larger,  and  IWK  is  an  array  of  dimension  5  or 
larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  GERK. 

The  argument  Y  of  GERK  is  an  array  of  dimension  n  or  larger,  and  the  arguments  T 
and  IND  are  variables.  (TOUT,  RERR,  AERR  need  not  be  variables.)  When  GERK  is 
initially  called,  it  is  assumed  that: 

T  =  a 

TOUT  =  b 

F(l),  ...  ,Y(n)  contain  the  values  yi  (a),  . . . ,  yn  (a) 

RERR  =  the  relative  error  tolerance  to  be  satisfied 

AERR  =  the  absolute  error  tolerance  to  be  satisfied 
IND  =  ±  1 

Normally  IND  =  1.  However,  if  only  a  single  step  in  the  direction  of  TOUT  is  to  be  taken, 
then  set  IND  =  —  1. 

GERROR  is  an  array  of  dimension  n  or  larger.  On  output  T  is  set  to  the  point  closest  to 
TOUT  for  which  the  equations  were  solved,  Y  contains  the  solution  at  T,  and  GERROR(t) 
is  an  estimate  of  the  error  of  Y(t)  for  i  =  1,  ...,n.  Also  IND  reports  the  status  of  the 
results.  GERK  sets  IND  to  one  of  the  following  values: 

IND  =  2  The  equations  were  successfully  solved  at  TOUT.  T  now  has  the 
value  TOUT. 

IND  =  -2  A  single  step  in  the  direction  of  TOUT  was  taken. 

IND  =  3  9000  derivative  evaluations  were  performed.  More  derivative  eval¬ 
uations  are  needed  to  reach  TOUT. 

IND  =  4  GERK  did  not  reach  TOUT  because  AERR  =  0.  AERR  must  be 
made  positive. 
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IND  =  5  Too  much  accuracy  has  been  requested.  AERR  and/or  RERR 
must  be  increased  in  value. 

IND  —  6  The  closeness  of  the  output  points  is  restricting  the  natural  step 
size  choice. 

IND  =  7  No  computation  was  performed.  An  input  error  was  detected.  The 
user  must  correct  the  error  and  call  GERK  again. 

If  IND  =  2  then  the  equations  have  been  solved  at  TOUT  =  b.  The  arrays  WK  and 
IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and  solving 
the  equations  at  a  new  point  c.  To  continue  the  integration  the  user  need  only  reset  TOUT 
to  the  new  point  c  and  call  GERK  again. 

If  IND  =  —2  then  to  continue  the  integration  another  single  step  just  call  GERK  again. 
In  the  single  step  mode  (IND  =  —1,  —2)  the  user  must  keep  in  mind  that  each  step  taken 
is  in  the  direction  of  the  current  TOUT.  Upon  reaching  TOUT  (which  is  indicated  by  IND 
being  set  to  2),  the  user  may  then  define  a  new  TOUT  and  set  IND  to  ±2  for  further 
integration. 

If  IND  =  3  then  to  continue  the  integration  just  call  GERK  again.  However,  if  IND  = 
4  then  the  user  must  first  reset  AERR  to  be  positive  before  GERK  can  be  recalled.  If  IND 
=  5  then  it  is  required  that  IND  be  reset  to  ±2  and  that  AERR  and/or  RERR  be  increased 
in  value.  If  this  is  not  done  then  the  run  will  be  terminated  by  a  STOP  instruction! 

If  IND  =  6  then  the  user  should  either  switch  to  another  routine,  or  he  should  use  the 
one  step  mode,  setting  IND  =  -2  for  the  next  call  to  GERK.  This  situation  is  discussed 
in  the  Initial  Value  Solvers  -  Introductory  Comments  section.  If  the  user  insists  on 
continuing  the  integration  with  GERK  in  the  standard  multistep  mode,  then  it  is  required 
that  IND  be  reset  to  2  before  GERK  is  recalled.  If  this  is  not  done  then  the  run  will  be 
terminated  by  a  STOP  instruction. 

If  after  going  from  a  to  b,  GERK  is  recalled  to  continue  the  integration  and  solve 
the  equations  at  a  new  point  c,  then  it  is  important  that  IND  be  set  to  ±2  instead  of 
±1.  Setting  IND  =  ±1  causes  the  integration  process  to  be  restarted^  thereby  eliminating 
the  information  being  saved  in  WK  and  IWK.  Restarting  wastes  time  and  is  normally  not 
needed.  The  one  exception  is  when  the  direction  of  integration  is  to  be  reversed.  Then  the 
integration  must  be  restarted. 

Notes. 

(1)  AERR  and  RERR  can  be  modified  each  time  that  GERK  is  called. 

(2)  When  continuing  an  integration,  one  may  switch  from  the  standard  multistep  mode 
(IND  =  2)  to  the  one  step  mode  (IND  =■  —2)  whenever  it  is  convenient  to  do  so. 

Input  Errors.  IND  —  7  occurs  when  one  of  the  following  conditions  is  violated: 

(1)  n  >  1 

(2)  T  ±  TOUT  when  IND  ±  ±1 

(3)  RERR  >  0  and  AERR  >0 

(4)  IND  =  ±1, ±2,3,4,  ,7 
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Accuracy  Considerations.  Error  control  in  GERK  is  almost  identical  to  that  in  RKF45. 
One  minor  difference  is  that  GERK  never  employs  relative  error  tolerances  less  than  3-10~11, 
whereas  RKF45  never  employs  relative  error  tolerances  less  than  10~12. 

The  only  significant  difference  between  GERK  and  RKF45  is  that  GERK  generates 
two  solutions  for  the  differential  equations,  whereas  RKF45  generates  only  one.  Let  y(t) 
and  y(t)  denote  the  solutions  generated  by  GERK  at  point  t.  One  of  these  solutions,  say 
y(t),  will  frequently  be  identical  to  the  solution  computed  by  RKF45.  When  going  from  t 
to  t  +  h,  the  step  size  h  is  selected  so  that  y(t  +  h)  satisfies  the  local  error  criterion.  After 
a  suitable  h  is  found  then  GERK  takes  two  steps,  each  of  length  h/2,  to  generate  y(i  +  h) 
from  y(i).  When  GERK  terminates,  say  at  point  T,  then  the  y(T)  solution  is  stored  in  the 
Y  array  and  GERK  estimates  the  error  of  y,(T)  to  be  (y,(T)  —  t/i(!T))/31  for  =  1?  . . .  }n. 

Programming.  GERK  employs  the  subroutines  GERKS  and  FEHL.  These  routines  were 
written  by  H.  A.  Watts  and  L.  F.  Shampine  (Sandia  Laboratories).  The  function  SPMPAR 
is  also  used. 

Reference.  Shampine,  L.  F.,  and  Allen,  R.  C.,  Numerical  Computing:  An  Introduction, 
W.  B.  Saunders,  Philadelphia,  1973. 
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ADAPTIVE  SOLUTION  OF  STIFF  DIFFERENTIAL  EQUATIONS 


Let  y'(t)  =  f(t,  y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations  where 
f{t,y)  =  ...,fn(t,y))  and  y(t)  =  (yi(t),  ...,y„(i)).  Assume  that  y(a)  is  known. 

Then  for  b  a  the  following  subroutines  are  available  for  computing  y(b).  These  routines 
are  designed  for  stiff  differential  equations.  The  algorithm  used  is  a  variable  order,  variable 
step  backward  differentiation  procedure. 

CALL  S FODE {F,  n,  Y, T, TOUT, INFO, RERR,AERR,IER, 

WK,£,IWK,m,RD,ID) 

RD  and  ID  are  arrays  defined  by  the  user  containing  any  real  and  integer  data  that  is 
needed  for  computing  /.  These  arrays  may  contain  any  information  that  the  user  desires. 
The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Y, DY,RD,ID) 

y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi  (t),  . . . ,  yn(t)  for  the 
argument  t.  F  computes  the  derivatives  yj(t),  . ..,y^(t)  using  y'(f)  =  /(t,y(t))  and  stores 
the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

INFO  is  an  array  of  dimension  4,  WK  an  array  of  dimension  £,  and  IWK  an  array  of 
dimension  m.  WK  and  IWK  are  work  spaces  for  the  routine,  and  INFO  is  an  array  defined 
by  the  user  containing  information  on  how  the  equations  are  to  be  treated. 

INFO(l):  Set  INFO(l)  =  0  on  an  initial  call  to  the  routine.  On  a  continua¬ 
tion  call  INFO(l)  =  1. 

INFO  (2):  Normally  INFO  (2)  =  0.  However,  INFO  (2)  =  1  when  the  inter¬ 
mediate  output  mode  is  desired  (see  below). 

INFO (3):  When  INFO(3)  =  0,  SFODE  proceeds  from  a  to  b  using  the  largest 
steps  that  are  appropriate.  If  b  is  passed  then  y(6)  is  obtained  by 
interpolation.  However,  for  some  problems  the  routine  cannot  be 
permitted  to  step  past  a  point  TSTOP  because  y'(t)  =  f(t,y(t)) 
is  discontinuous  or  not  defined  beyond  TSTOP.  When  this  is  the 
case  set  INFO(3)  =  1  and  WK(l)  =  TSTOP. 

INFO(4):  When  proceeding  from  a  to  b,  the  n  x  n  Jacobian  matrix  Jf(t)  = 

(dfi/dyi)  is  computed  and  stored  in  WK.  Normally  it  is  assumed 
that 

INFO  (4)  =  0 
£  >  250  +  lOn  +  n2 
m  >  55'+  n. 

However,  if  J f  (t)  is  banded  for  all  t,  having  the  lower  and  upper 
band  widths  mt  and  mu  where  2mt  +  mu  <  n,  then  the  following 
setup  can  be  used: 

INFO  (4)  =  1 
IWK(l)  =  mt 
IWK(2)  =  mu 

£  ^  250  +  lOn  +  (2m£  +  mu  +  l)n 
m  >  55  +  n 
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T,  TOUT,  RERR,  and  AERR  are  variables,  and  the  argument  Y  of  SFODE  is  an 
array  of  dimension  n.  On  an  initial  call  to  the  routine  it  is  assumed  that 

INFO(l)  =  0 

T  =  o 

TOUT  =  b 

F(l),  . . . ,  Y (n)  contain  the  values  t/i(o),  . . . , yn(a) 

RERR  =  the  relative  error  tolerance  to  be  satisfied  (RERR  >  0) 

AERR  =  the  absolute  error  tolerance  to  be  satisfied  (AERR  >0). 

IER  is  a  variable.  When  SFODE  terminates  T  is  the  final  point  where  the  equations 
were  solved,  Y  contains  the  solution  at  T,  and  IER  reports  the  status  of  the  results.  IER 
is  assigned  one  of  the  following  values: 

IER  =  1  A  step  was  taken  in  the  intermediate  output  mode.  TOUT  Was 

not  reached.  To  continue,  call  the  routine  again. 

IER  =  2  The  solution  at  TOUT  was  obtained  by  stepping  exactly  to  TOUT. 

IER  =  3  The  solution  at  TOUT  was  obtained  by  stepping  past  TOUT  and 

then  interpolating.  On  output  T  =  TOUT. 

IER  =  —1  500  steps  have  been  taken.  TOUT  has  not  been  reached.  To 
continue,  call  the  routine  again. 

IER  =  —2  The  tolerances  RERR  and  AERR  were  too  stringent.  RERR  and 
AERR  have  been  modified  by  the  routine.  The  tolerances  may  be 
further  modified  by  the  user  if  he  desires.  To  continue,  call  the 
routine  again. 

IER  =  -3  In  this  case  AERR  =  0.  SFODE  stopped  when  y»  became  0. 

INFO(l)  was  set  to  — t.  To  continue  set  AERR  to  be  positive, 

INFO(l)  =  1,  and  call  the  routine  again. 

IER  =  —  6  Convergence  failed  on  the  last  attempted  step.  An  inaccurate 
Jacobian  matrix  may  be  the  problem.  To  continue,  restart  the 
routine  by  setting  INFO(l)  =  0  and  call  the  routine  again. 

IER  =  —  7  Repeated  error  test  failures  occurred  on  the  last  attempted  step. 

The  problem  should  be  reexamined.  A  singularity  may  be  present 
in  the  solution.  To  continue,  restart  by  setting  INFO(l)  =  0  and 
call  the  routine  again. 

IER  <  —33  An  input  error  was  detected  (see  below). 

When  IER  >  —2,  then  INFO(l)  =  1  on  output. 

When  the  equations  are  solved  at  TOUT  (IER  =  2  or  3),  integration  can  be  continued 
along  the  axis  to  solve  the  equations  at  a  new  point  c  beyond  TOUT.  To  continue,  one 
need  only  set  TOUT  to  the  new  value  c  and  call  the  routine  again.  When  continuing  an 
integration  where  INFO(l)  =  1,  never  modify  T,  Y,  WK,  IWK,  INFO(3),  and  INFO(4). 
However,  INFO (2),  RERR,  AERR,  RD,  and  ID  may  be  modified  at  any  time. 

Intermediate  Output  Mode.  If  one  wishes  to  study  the  behavior  of  the  solution  y(t)  as 
the  routine  steps  from  T  to  TOUT,  then  set  INFO  (2)  =  1.  Then  SFODE  will  stop  after 
each  successful  step  (yielding  IER  =  1)  until  TOUT  is  reached.  One  may  switch  from  the 
standard  mode  of  operation  (INFO(2)  =  0)  to  the  intermediate  output  mode  (INFO(2)  = 
1)  or  visa  versa  at  any  time. 
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Remark.  The  diagnostic  IER  =  —  1  does  not  state  that  500  steps  have  been  taken  on 
the  current  call  to  SFODE.  On  an  initial  call  to  the  routine  the  step  counter  is  set  to  0. 
On  continuation  calls,  the  counter  continues  to  increase  until  500  steps  have  accumulated. 
When  IER  =  —  1  is  reported,  the  counter  is  reset  to  0,  and  only  then  does  the  step  counting 
begin  again. 

Input  Errors.  IER  is  set  to  one  of  the  following  values  when  an  input  error  is  detected. 
IER  =  -33  n  <  1 
IER  =  -34  RERR  <  0 
IER  =  -35  AERR  <  0 

IER  =  —36  The  routine  has  been  called  with  TOUT,  but  it  has  also  been  told 
not  to  step  past  the  point  TSTOP. 

IER  =  —37  T  =  TOUT.  This  is  not  permitted  on  continuation  calls. 

IER  =  —38  The  user  has  modified  T. 

IER  =  —39  TOUT  is  not  beyond  T.  An  attempt  is  being  made  to  change  the 
direction  of  integration  without  restarting. 

IER  =  -40  The  Jacobian  matrix  is  banded.  However,  m*  and  mu  do  not 
satisfy  0  <  mi  <  n  and  0  <  mu  <  n. 

IER  =  -41  l  <  250  +  lOn  +  n2 

IER  =  -42  t  <  250  +  lOn  +  (2 mt  +  mu  +  l)n 

IER  =  —43  m  <  55  +  n 

IER  =  —44  INFO(l)  is  incorrect. 

After  the  error  is  corrected,  set  INFO(l)  =  0  and  call  the  routine  again. 

Error  Control.  Assuming  that  SFODE  has  the  correct  value  for  y(t),  let  e,-  denote  the 
error  generated  in  computing  y»(t  +  h)  for  *  =  1, . . . ,  n  when  SFODE  steps  from  t  to  t  +  h. 
The  routine  attempts  at  each  step  to  maintain  the  accuracy  ^Ei(ej/u;,)2  <  1  where  Wi  = 
RERR  |y»(t)|  +  AERR.  When  this  criterion  is  satisfied,  |  <  y/nwi  for  i  =  1,  . . .  ,n.  This 
criterion  includes  as  special  cases  relative  error  (AERR  =  0)  and  absolute  error  (RERR  = 
0).  However,  if  AERR  =  0  and  y*(f)  =  0  for  some  i,  then  this  criterion  cannot  be  applied 
and  IER  =  —  3  occurs. 

When  proceeding  from  T  to  TOUT,  the  routine  continually  readjusts  its  order  and  step 
size  so  as  to  maintain  accuracy  at  each  step.  However,  no  attempt  is  made  to  control  the 
progressive  erosion  of  accuracy  that  can  occur  when  the  steps  accumulate.  Since  the  erosion 
of  accuracy  can  be  significant,  at  times  one  may  wish  to  double-check  the  results.  If  the 
problem  is  nonstifF  or  mildly  stiff  for  an  interval,  then  the  best  procedure  is  to  compare  the 
results  obtained  by  SFODE  with  those  obtained  by  ODE  for  the  interval.  ODE  normally 
maintains  greater  accuracy  than  SFODE.  However,  if  the  problem  is  extremely  stiff  then 
rerun  the  problem  with  SFODE.  On  the  second  run,  request  greater  accuracy. 

Programming.  SFODE  calls  the  subroutines  STFODE  and  ZZZJAC.  STFODE  employs 
the  subroutines  LSOD1,  HSTART,  INTYD,  STOD,  CFOD,  PJAC,  SLVS,  SGBFA,  SGBSL, 
SGEFA,  SGESL,  SAXPY,  and  SSCAL,  and  the  functions  VNORM,  VNWRMS,  ISAMAX, 
SDOT,  and  SPMPAR.  The  routines  save  and  exchange  information  in  a  labeled  common 
block  having  the  block  name  DEBDF1.  STFODE  is  a  modification  by  A.  H.  Morris  of  the 
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subroutine  DEBDF,  designed  by  L.  F.  Shampine  and  H.  A.  Watts  (Sandia  Laboratories). 
DEBDik  appears-  in :  the  SLATEC  library.  STFODE  is  a  driver  for  a  modification  of  the 
codejL£0©E,;-vmtten  by  A.  C.  Hindmarsh  (Lawrence  Livermore  Laboratory). 

yvflrl  i  - 

2  a  irc^GAfeb  S  FOD  El  {F,  n,  Y,  T, TOUT,  INFO,  RERR, AERR, IER, 

WK,£,IWK,m,RD,ID) 

differs  from  SFODE  only  in  the  treatment  of  RERR  and  AERR.  In  SFODE1, 
RERR  and  AERR  are  arrays  of  dimension  n.  RERR(t)  and  AERR(r')  are  relative  and 
absolute  error  tolerances  to  control  the  accuracy  of  the  itK  solution  component  y,(t)  for 
i  —  1,  . . .  ,  n.  Let  e,-  denote  the  error  generated  in  the  computation  of  +  h)  from  yi(t) 
when  SFODE1  steps  from  t  to  t  +  h.  Then  SFODE1  attempts  at  each  step  to  maintain  the 
accuracy  ^Ei(ei/u;,)2  <  1  where  tUj  =  RERR(«')|yj(t)|  +  AERR(t).  When  this  criterion  is 
satisfied  |e,|  <  y/nwi  for  i  =  1,  . . .  ,n.  However,  if  AERR(i)  =  0  and  y*(t)  =  0  for  some  t, 
then  the  criterion  cannot  be  applied  and  IER  =  —3  occurs. 

When  IER  references  RERR  and  AERR,  the  settings  for  IER  provide  the  following 
information: 

IER  =  —2  The  accuracy  required  by  RERR  and  AERR  is  too  stringent. 

RERR  and  AERR  have  been  modified  by  the  routine.  RERR 
and  AERR  may  be  further  modified  by  the  user  if  he  desires.  To 
continue,  call  SFODE1  again. 

IER  =  —3  SFODE1  stopped  when  y^  became  0  and  AERR(»)  =  0.  INFO(l) 
was  set  to  —  t.  To  continue  set  AERR(»)  to  be  positive,  INFO(l) 

=  1,  and  call  the  routine  again. 

IER  =  —34  (Input  error)  RERR(«)  <  0  for  some  t. 

IER  =  -35  (Input  error)  AERR(t)  <  0  for  some  i. 

RERR  and  AERR  may  be  modified  on  any  continuation  call  to  SFODE1. 

Programming.  SFODE1  calls  the  subroutines  STFODE  and  ZZZJAC. 
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FOURTH-ORDER  RUNGE-KUTTA 


Let  y'(i)  =  /(t,y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f{t,y)  =  (/i(t,y),  ■■•,fn(t,y))  and  y(t)  =  (yi(t),  ...,yn(t)).  Assume  that  y(t0)  is 
known.  Then  for  a  small  real  number  h,  the  subroutine  RK  is  available  for  computing 
y(io  +  h).  RK  employs  the  standard  fourth-order  Runge-Kutta  procedure. 

CALL  R K{n,T,h,A,F) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Z) 

Z  is  an  array  of  dimension  n  containing  the  values  yi(i),.. . ,yn(t)  for  the  argument  t.  F 
computes  the  derivatives  yi(£), . . .  ,y'n{t)  using  y'(t)  =  f(t, y(i))  and  stores  the  results  in  Z, 
thereby  destroying  the  original  data  in  Z.  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

T  is  a  variable  having  the  value  to  and  A  an  array  of  dimension  3 n  or  larger.  It 
is  assumed  that  A(l),  ...,A(n)  contain  the  values  yi(£o)>  .  ..,y,j(£o)-  If  h  =  0  then  RK 
computes  the  derivatives  yi(£o),  .  ..,yJ,(to)  and  stores  them  in  A(n  +  1),...,A(2»).  If 
h  0  then  it  is  assumed  that  the  derivatives  y'i(to),  . . .  ,y^(£o)  have  already  been  computed 
and  stored  in  A(n  +  1),  ...,A(2n).  In  this  case,  when  RK  is  called,  the  values  yi(to  + 
h),  . . .  ,yn(to  +  h)  and  derivatives  yi(io  +  h),  ...  ,  y'n(to  +  h)  are  computed  and  stored  in 
A(l),  . . . ,  A(2n).  Also  T  is  reset  to  the  value  to  +  A. 

Note.  The  area  A(2n  +1),  . . . ,  A(3n)  serves  as  work  space  for  the  routine. 

Example.  Consider  the  equations 
x'(t)  =  y  (t) 
y'(t)  =  -x(t) 

where  a:(0)  =  0  and  y(0)  =  1.  The  following  code  may  be  used  for  solving  these  equations 
at  the  points  .01,  .02,  . . . ,  1.00,  and  storing  the  results  in  the  arrays  X  and  Y. 

DIMENSION  A(6),  X(100),  Y(100) 

EXTERNAL  FUN 

T  =  0.0 

H  =  .01 

A(l)  =  0.0 

A(2)  =  1.0 

A(3)  =  1.0 

A(4)  =  0.0 

DO  10  I  =  1,  100 

CALL  RK(2,T,H,A,FUN} 

X(I)  =  A(l) 

10  Y(I)  =  A(2) 
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Here  FUN  may  be  defined  by: 

SUBROUTINE  FUN(T,Z) 

DIMENSION  Z(2) 

X=Z(1) 

Y  =  Z(2) 

Z(l)  =  Y 
Z(2)  =  -X 
RETURN 
END 

Note  that  the  statements  A(3)  =  1.0  and  A(4)  =  0.0,  which  store  the  derivatives  i'(0)  and 
y'(0)  in  A(3)  and  A(4),  can  be  replaced  with  CALL  RK(2,T,0.0,A,FUN). 

Programmer.  A.H.  Morris. 


EIGHTH-ORDER  RUNGE-KUTTA 


Let  y'(t)  =  f(t,y(t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f(t,y)  =  (/i(t,y),  ...,fn(t,y))  and  y(t)  =  (yi(t),  . . .  ,yn(t)).  Assume  that  y(t0)  is 
known.  Then  for  a  small  real  number  h,  the  subroutine  RK8  is  available  for  computing 
y(io  +  ^)- 

CALL  RK8(n,  T,  h,  Y,  DY,WK,  F) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Z) 

Z  is  an  array  of  dimension  n  containing  the  values  yi(t), . . .  ,y„(t)  for  the  argument  t.  F 
computes  the  derivatives  yj(i), .. .  ,y'n(t)  using  y'(t)  =  f(t,y(t))  and  stores  the  results  in  Z, 
thereby  destroying  the  original  data  in  Z.  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

T  is  a  variable  having  the  value  to,  and  Y  and  DY  are  arrays  of  dimension  n.  It  is 
assumed  that  Y  contains  the  values  yi(t0),  ...  ,yn(to)-  If  h  =  0  then  RK8  computes  the 
derivatives  yi(t0),  . . .  ,y^(t0)  and  stores  them  in  DY.  If  h  0  then  it  is  assumed  that  the 
derivatives  yi(to),  •  •  ■  ,y'n{to )  have  already  been  computed  and  stored  in  DY.  In  this  case, 
when  RK8  is  called,  the  values  yi(t0  +  h),  ..  .,yn{t0  +  h )  and  derivatives  y[ (t0  +  h),  . . . , 
y'n(to  +  h)  are  computed  and  stored  in  Y  and  DY,  thereby  destroying  the  original  data  in 
Y  and  DY.  Also  T  is  reset  to  the  value  to  +  h. 

WK  is  an  array  of  dimension  8n  or  larger  that  is  used  for  a  work  space  by  the  routine. 

Algorithm.  The  routine  employs  formulae  (8-12)  given  on  p.  34  of  the  reference. 

Remarks.  RK8  is  used  in  the  same  manner  as  the  routine  RK.  RK8  takes  more  time  and 
storage  than  RK,  but  may  be  more  accurate. 

Reference.  Shanks,  E.  B.,  “Solutions  of  Differential  Equations  by  Evaluations  of  Functions,” 
Math.  Comp.  20  (1966),  pp.  21-38. 

Programmer.  A.  H.  Morris 
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SEPARABLE  SECOND-ORDER  ELLIPTIC  EQUATIONS 
ON  RECTANGULAR  DOMAINS 

Given  a  separable  elliptic  equation 

“1“  d-  -I-  d[y)iiyy  +  e(y)«y  +  /(y)«  =  g{x,  y) 

on  the  rectangle  a*  <  x  <  a2,bi  <  y  <  b2,  where  u  is  periodic  in  x  or  y,  or  u  or  its  normal 
derivative  du/dn  is  given  on  each  of  the  edges.  For  m,n  >  1  let  =  aj.  +  (»  -  l)h  and 

y j  =  61  +  {]  -  l)fc  where  h  =  (a2  -  ax)/(m  -  1),  k  =  (b2  -  6i)/(n  —  1),  *  =  1, _ ,  m,and 

j  —  1,  . . .  ,n.  Then  the  subroutine  SEPDE  is  available  for  computing  u  at  the  points  (®«,yy). 

CALL  SEPDE(COFX, COFY, y,ITYPE,BVAL, IORD, ax,  a2,  m,  bu  b2,  n, 

J7,ku,FP,  £,IND) 

It  is  assumed  that  m  >  7  and  n  >  6.  [/  is  an  m  x  n  matrix.  The  argument  ku  is  the 
number  of  rows  in  the  dimension  statement  for  U  in  the  calling  program.  When  SEPDE 
is  called,  if  the  elliptic  equation  is  solved  then  U{i,j)  =  u(zj,yy)  for  *  =  1,  ...,m  and 
j= 

The  input  argument  IORD  is  the  order  of  the  approximation  procedure  to  be  used. 
IORD  may  have  the  values  2  or  4. 

The  argument  COFX  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 
CALL  COFX(x,  A,  B^C) 

A,  B,  and  C  are  variables.  COFX  sets  A  =  a(x),  J3  =  6(i),  and  C  =  c(x)  for  the  argument 

x.  COFX  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  argument  COFY  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 
CALL  COFY (y,D,E,F) 

D,  E ,  and  F  are  variables.  COFY  sets  D  =  d(y),  E  =  e(y),  and  F  =  f{y)  for  the  argument 

y.  COFY  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  argument  g  is  the  name  of  a  user  defined  function,  where  y(x,y)  gives  the  right 
hand  side  of  the  elliptic  equation  for  all  ai  <  x  <  a2,  &i  <  y  <  &2.  The  argument  g  must  be 
declared  in  the  calling  program  to  be  of  type  EXTERNAL. 


Boundary  Conditions.  The  edges  of  the  rectangular  domain  are  labeled  in  a  clockwise 
manner  as  follows: 


*  =  2 


<  —  3 

»  =  4 


*  =  1 


edge  1  =  {  (z,&i)  |  01  <  x  <  a2  } 

edge  2  =  {  (ax,  y)  |  <  y  <  b2  } 

edge  3  =  {  [x,b2)  \  <  x  <  a2  } 

edge  4  =  {  (a2,  y)  |  ix  <  y  <  b2  } 


ITYPE  is  an  array  of  dimension  4.  For  edge  *  (*  =  1,  . . .  ,4),  ITYPE(i)  specifies  the  type  of 
boundary  condition  on  the  edge.  ITYPE(j)  must  be  set  by  the  user  to  one  of  the  following 
values: 

ITYPE(t)  =  0  It  is  assumed  that  u  is  given  on  the  edge. 
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ITYPE(»)  =  1  If  t  =  1  or  :  =  3  then  uv  is  given  on  the  edge:  Otherwise,  if  t  =  2 
or  i  =  4  then  ux  is  given  on  the  edge. 

ITYPE(«)  =  — 1  If  i  =  1  or  »  =  3  then  it  is  assumed  that  u  is  periodic  in  y;  i.e., 
u(x,  y  +  62  —  61)  =  u(x,y )  for  all  x, y.  In  this  case  ITYPE(»)  must 
be  —1  for  both  t  =  1  and  *  .==  3.  If  i  =  2  or  t  =  4  then  it  is  assumed 
that  u  is  periodic  in  x;  i.e.,  u(x  +  02  —  ai,y)  =  u(x,  y)  for  all  x,  y. 

In  this  case  ITYPE(i)  must  be  —1  for  both  i  =  2  and  t  =  4. 

The  argument  BVAL  is  the  name  of  a  user  defined  function.  BVAL(i,x, y)  is  defined  for 
any  point  (x,  y)  on  edge  t  when  ITYPE(z)  =  0  or  1,  where 

(  u(x,y)  if  ITYPE(z)  =  0 

BVAL(i,  x,  y)  -  i  uy(x,y)  if  ITYPE(z)  =  1  (»  =  1  or  i  =  3) 

[  ux(x,y)  if  ITYPE(i)  =  1  (»•  =  2  or  «  =  4) 

The  function  BVAL(«,x,y)  is  ignored  when  ITYPE(t)  =  —  1.  BVAL  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

W  is  an  array  of  dimension  £  that  is  a  work  space.  The  argument  £  is  a  variable  whose 
value  depends  on  IORD,  m,n,  and  the  types  of  boundary  conditions  used.  Let  v  be  the 
largest  integer  <  log2  n  and  £1  =  (u  —  1)21,+2  +  u  +  14m  +  12n  -j-  6.  Then 
£>  £i  if  IORD  =  2. 

£  >  £1  +  mn  if  IORD  =  4. 

When  the  routine  terminates.,  £  will  have  been  reset  to  the  actual  amount  of  storage 
needed. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  SEPDE  terminates,  IND 
has  one  of  the  following  values: 

IND  =  0  The  solution  U  was  obtained. 

IND  =  —  1  A  constant  fwhich  is  stored  in  WflD  was  subtracted  from  the 


IND  = 
IND  = 
IND  = 


IND  = 
IND  = 
IND  = 
IND  = 
IND  = 


IND  = 


right  hand  side  of  the  equation  in  order  to  obtain  a  solution  U . 
The  solution  is  a  weighted  minimal  least  squares  solution  of  the 
original  problem. 

1  (Input  error)  a\  >  <22  or  61  >  62- 

2  (Input  error)  ITYPE(t)  7^  0,±1  for  some  edge  t. 

4  The  approximating  linear  system  of  equations  is  not  diagonally 
dominant.  This  cannot  occur  when  m  and  n  are  sufficiently  large. 
Increase  m  and  n,  and  reset  L 

5  (Input  error)  ku  <  m. 

6  (Input  error)  m  <  7. 

7  (Input  error)  n  <  6. 

8  (Input  error)  IORD  ^  2, 4. 

10  (Input  error)  a(x)d(y)  <  0  for  some  interior  point  (x,y)  of  the 
rectangle.  This  violates  the  assumption  that  the  equation  is  ellip¬ 
tic. 

11  (Input  error)  £  was  too  small.  £  has  been  reset  to  the  minimum 
amount  of  storage  needed  for  W. 
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IND  =  12  (Input  error)  ITYPE(t)  =  -1  for  edge  1  or  3,  but  not  for  both 
edges. 

IND  =  13  (Input  error)  ITYPE(t)  =  -1  for  edge  2  or  4,  but  not  for  both 
edges. 

Precision.  If  IORD  =  2  then  the  elliptic  equation  is  approximated  by  a  set  of  linear  equa¬ 
tions  using  finite  differences.  Otherwise,  if  IORD  =  4  then  the  approximating  equations 
are  obtained  by  deferred  corrections.  The  most  accuracy  is  achieved  when  ITYPE(i)  =  1 
boundary  conditions  are  not  involved.  For  m,  n  >  100,  3-4  digit  accuracy  may  be  attained 
when  IORD  =  2  and  7-8  digit  accuracy  when  IORD  =  4.  When  ITYPE(i)  =  1  boundary 
conditions  are  used,  then  for  m,  n  >  100,  2-3  digits  may  be  attained  when  IORD  =  2  and 
5-6  digits  when  IORD  =  4. 

Programming.  SEPDE  is  an  interface  by  A.  H.  Morris  for  SEPELL,  a  modification  of  the 
routine  SEPELI  described  in  the  reference.  SEPELI  was  developed  by  John  C.  Adams,  being 
supported  (in  part)  by  codes  written  by  Paul  Swarztrauber  and  Roland  Sweet  (National 
Center  for  Atmospheric  Research,  Boulder,  Colorado).  SEPDE  employs  the  subroutines 
PDEDGE,  SEPELL,  SEPELI,  CHKPRM,  CHKSNG,  ORTHG,  MINSOL,  TRISP,  DEFER, 
DXFN,  DYFN,  BLKTRI,  BLKTR1,  COMPB,  PRODO,  PRODP,  CPRODO,  CPRODP,  IN- 
DXA,  INDXB,  INDXC,  PPADD,  TQLRTO  and  functions  PSGF,  BSRH,  PPSGF,  PPSPF, 
SPMPAR.  The  routines  exchange  information  in  the  labeled  common  blocks  having  block 
names  CBLKT  and  SPLP. 

Example.  Consider  (1+i)2ui;j -2(1  + z)ux  +  uyy  =  3(l+z)4  siny  for  0  <  x  <  1  and  ]y|  <  ir 

where  +r(0>y)  =  4siny  |y|  <  n 
u(l,y)  =  16  siny 

and  u  is  periodic  in  y.  This  problem  has  the  solution  tt  =  (1  + z)4  siny.  Let 

ITYPE(l)  =  -1 
ITYPE(2)  =  1 

ITYPE(3)  =  -1 
ITYPE(4)  =  0. 

Then  the  following  routines  and  functions  may  be  used  for  describing  the  problem.  (Here 
g  =  GVAL.) 

SUBROUTINE  COFX  (X,A,B,C) 

T  =  1.0  +  X 
A  =  T*T 
B  =  — 2.0*T 
C  =  0.0 
RETURN 
END 

SUBROUTINE  COFY  (Y,D,E,F) 
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D  =  1.0 
E  =  0.0 
F  =  0.0 
RETURN 
END 

REAL  FUNCTION  GVAL  (X,Y) 

GVAL  =  3.0*(1.0  +  X)*  *  4*SIN(Y) 

RETURN 

END 

REAL  FUNCTION  BVAL  (I,X,Y) 

BVAL  =  4.0*SIN(Y) 

IF  (I  .EQ.  4)BVAL  =  4.0*BVAL 

RETURN 

END 

COFX,  COFY,  GVAL,  and  BVAL  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

Reference.  Adams,  J.,  Swarztrauber,  P.,  and  Sweet,  R.,  FISHPAK:  Efficient  FORTRAN 
Subprograms  for  the  Solution  of  Separable  Elliptic  Partial  Differential  Equations, 
Version  3.  National  Center  for  Atmospheric  Research,  Boulder,  Colorado,  1978. 
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UNIFORM  RANDOM  NUMBER  GENERATOR 


The  following  subroutine  is  available  for  generating  a  sequence  of  uniform  variates  in  the 
interval  (0, 1). 

CALL  U  RN  G(ix,A,  n,IERR) 

The  argument  n  is  the  number  of  variates  to  be  generated.  A  is  an  array  of  dimension 
n  or  larger,  and  ix  and  IERR  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for 
initializing  the  sequence  of  variates.  It  is  assumed  that  1  <  ix  <  231  —  1.  When  URNG 
is  called,  if  no  input  errors  are  detected  then  IERR  is  set  to  0  and  n  uniform  variates  are 
stored  in  A.  On  output,  ix  is  a  new  seed  for  generating  more  variates. 

Error  Return.  IERR  =  1  if  n  <  0  and  IERR  =  2  if  ix  is  not  a  proper  seed. 

Usage.  A  given  seed  always  initiates  the  same  set  of  variates.  Thus,  the  following  two  sets 
of  instructions 

(1)  IX  =  103 

CALL  URNG(IX,A,30,IERR) 

IX  =  103 

(2)  CALL  URNG  (IX, A, 20, IERR) 

CALL  URNG  (IX,A(2 1) ,  10, IERR) 

generate  the  same  30  variates. 

Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  i  in  the 
interval  |t|  <  231  —  1. 

Programming.  Written  by  Linus  Schrage  (University  of  Chicago).  Adapted  by  A.H.  Morris. 

Reference.  Schrage,  Linus, “A  More  Portable  Fortran  Random  Number  Generator,”  ACM 
Trans.  Math  Software  5  (1979),  pp.  132-138. 
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GAUSSIAN  RANDOM  NUMBER  GENERATOR  USING  THE 
BOX-MULLER  TRANSFORMATION 


The  following  subroutine  is  available  for  generating  a  sequence  of  normal  variates  from  a 
normal  distribution  with  mean  0  and  standard  deviation  1. 

CALL  N  R N G (ix, A,  n ,IERR) 

The  argument  n  is  the  number  of  variates  to  be  generated.  A  is  an  array  of  dimension 
n  or  larger,  and  ix  and  IERR  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for 
initializing  the  sequence  of  variates.  It  is  assumed  that  1  <  ix  <  231  —  1.  When  NRNG 
is  called,  if  no  input  errors  are  detected  then  IERR  is  set  to  0  and  n  normal  variates  are 
stored  in  A.  On  output,  ix  is  a  new  seed  for  generating  more  variates. 

Error  Return.  IERR  =  1  if  n  <  0  and  IERR  =  2  if  ix  is  not  a  proper  seed. 

Algorithm.  When  NRNG  is  called,  an  even  number  of  uniform  variates  «i,  ...  ,um  is  gen¬ 
erated  (m  =  n  if  n  is  even  and  m  =  n  +  1  if  n  is  odd).  Then  the  Box-Muller  transformation 

o*  =  \f— 2  In  u*;  cos  27fUfc+i 
ak+ 1  =  \/-21nUfcsin2jrufc-l.i  (fc  =  1,3,5,  ... ) 

is  applied  to  obtain  n  normal  variates  oi,  ...,a„.  This  transformation  generates  pairs  of 
normal  variates  (a1}  <12),  (03,04),  . . .  from  the  corresponding  pairs  of  uniform  variates.  If  n 
is  odd  then  only  the  first  variate  of  the  final  pair  (an,an+i)  is  computed. 

Usage.  A  given  seed  always  generates  the  same  sequence  of  uniform  variates.  Thus,  if  we 


consider 

the  following  three  sets  of  instructions 

(1) 

IX  =  73 

CALL  NRNG  (IX, A, 30, IERR) 

(2) 

IX  =  73 

CALL  NRNG(IX,A,10,IERR) 

CALL  NRN G  (IX , A(  1 1)  ,20, IERR) 

(3) 

IX  =  73 

CALL  NRNG  (IX, A, 9, IERR) 

CALL  NRNG  (IX,  A(10)  ,20, IERR) , 

then  we  note  that  (1)  and  (2)  generate  the  same  30  normal  variates.  Also  (3)  produces 
29  of  these  30  variates,  skipping  the  10th  normal  variate.  The  reason  for  this  is  that  the 
request  in  (3)  for  9  normal  variates  requires  10  uniform  variates  to  be  generated.  The  10 
uniform  variates  could  be  used  for  computing  10  normal  variates  (as  is  done  in  (2)).  How¬ 
ever,  since  only  9  normal  variates  are  requested,  computation  of  the  10th  normal  variate 
that  would  usually  be  generated  is  skipped. 
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Remark.  NRNG  calls  the  subroutine  URNG  for  the  uniform  variates.  Thus,  it  is  assumed 
that  the  integer  arithmetic  being  used  handles  all  integers  t  in  the  interval  |t'|  <  2S1  —  1. 

Programmer.  A.H.  Morris 
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APPENDIX 


Installation  Of  The  NSWC  Library 

Two  versions  of  the  code  for  the  NSWC  library  are  maintained,  differing  only  in  the 
declaration  of  assumed  size  arrays.  In  the  1966  version,  statements  such  as  REAL  A(l)  are 
frequently  used  in  declaring  as  arrays  arguments  A  of  a  function  or  subroutine.  In  the  1977 
version,  statements  such  as  REAL  A(*)  are  used  for  declaring  the  arrays.  The  1966  version 
must  be  used  by  all  Fortran  compilers  which  satisfy  the  1966  standard,  and  it  may  be  used 
by  almost  all  the  compilers  which  satisfy  the  1977  standard.  The  1977  version  can  only  be 
used  by  the  compilers  which  satisfy  the  1977  standard. 

Code  for  the  library  can  be  obtained  on  7-track  and  9-track  tapes,  and  on  5±  inch 
disks  that  can  be  read  by  the  IBM  PC.  Two  files  are  given  on  a  tape.  The  first  file  contains 
the  1966  version  of  the  code,  and  the  second  file  contains  the  1977  version.  The  1977  version 
is  normally  provided  on  the  disks. 

The  first  function  in  the  NSWC  library,  namely  IPMPAR,  must  be  modified  for  the 
particular  Fortran  being  used.  IPMPAR  provides  the  integer  constants  which  characterize 
the  integer,  single  precision,  and  double  precision  arithmetics  being  used  (see  pp.3-4). 

Instructions  are  given  in  the  in-line  documentation  of  IPMPAR  for  defining  the 
constants  that  are  needed. '  If  constants  are  not  provided  for  the  compiler  being 
used,  then  the  Fortran  manual  for  the  compiler  normally  gives  the  constants  for 
the  integer  arithmetic.  However,  help  may  be  needed  in  obtaining  the  constants  for 
the  single  and  double  precision  arithmetics.  The  subroutines  MACH  and  RADIX 
are  provided  for  this  purpose. 

MACH  and  RADIX,  and  their  subroutines  MACH1,  STORE2,  MACH2,  DSTOR2 
are  the  next  subprograms  after  IPMPAR.  Instructions  for  the  use  of  MACH  and 
RADIX  are  given  in  MACH.  These  subroutines  are  experimental.  They  are  pro¬ 
vided  only  as  an  aid  for  obtaining  the  constants  for  the  single  and  double  precision 
arithmetics.  They  are  not  used  by  any  of  the  functions  and  subroutines  in  the 
NSWC  library,  and  they  are  not  considered  to  be  part  of  the  library.  MACH1 
and  MACH2  perform  some  writing.  None  of  the  functions  and  subroutines  in  the 
NSWC  library  perform  I/O. 

After  IPMPAR  has  been  defined,  the  remainder  of  the  library  can  be  installed.  None  of 
the  remaining  code  needs  any  modification.  Codes  for  the  functions  and  subroutines  appear 
approximately  in  the  order  that  they  appear  in  the  manual. 
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